/ Hex Artifact Content
Login

Artifact cc237b8aa62348685b36d06f1b6beb10dfea39ae:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  y are supported 
07d0: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
07e0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
07f0: 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
0800: 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64  n writers should
0810: 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a   be aware that.*
0820: 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  * experimental i
0830: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
0840: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
0850: 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65  in point release
0860: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d  s..**.** These m
0870: 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65  acros used to re
0880: 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73  solve to various
0890: 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c   kinds of compil
08a0: 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a  er magic that.**
08b0: 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20   would generate 
08c0: 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73  warning messages
08d0: 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65 20   when they were 
08e0: 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a  used.  But that.
08f0: 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  ** compiler magi
0900: 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72  c ended up gener
0910: 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75  ating such a flu
0920: 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72  rry of bug repor
0930: 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61  ts.** that we ha
0940: 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20  ve taken it all 
0950: 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63  out and gone bac
0960: 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c  k to using simpl
0970: 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73  e.** noop macros
0980: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
0990: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23  ITE_DEPRECATED.#
09a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
09b0: 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a  PERIMENTAL../*.*
09c0: 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20 73  * Ensure these s
09d0: 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20  ymbols were not 
09e0: 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20  defined by some 
09f0: 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 20  previous header 
0a00: 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  file..*/.#ifdef 
0a10: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
0a20: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0a30: 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66  RSION.#endif.#if
0a40: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0a50: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65  ON_NUMBER.# unde
0a60: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a70: 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a  _NUMBER.#endif..
0a80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
0a90: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62  Compile-Time Lib
0aa0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0ab0: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  bers.**.** ^(The
0ac0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ad0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0ae0: 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71   macro in the sq
0af0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a  lite3.h header.*
0b00: 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61  * evaluates to a
0b10: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
0b20: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69  that is the SQLi
0b30: 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68  te version in th
0b40: 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59  e.** format "X.Y
0b50: 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20 74  .Z" where X is t
0b60: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
0b70: 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20   number (always 
0b80: 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33  3 for.** SQLite3
0b90: 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d  ) and Y is the m
0ba0: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
0bb0: 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65  ber and Z is the
0bc0: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e   release number.
0bd0: 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  )^.** ^(The [SQL
0be0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bf0: 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ER] C preprocess
0c00: 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65  or macro resolve
0c10: 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  s to an integer.
0c20: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c 75  ** with the valu
0c30: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0c40: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0c50: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65   X, Y, and Z are
0c60: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d   the same.** num
0c70: 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51  bers used in [SQ
0c80: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e  LITE_VERSION].)^
0c90: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56  .** The SQLITE_V
0ca0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f  ERSION_NUMBER fo
0cb0: 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65  r any given rele
0cc0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ase of SQLite wi
0cd0: 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61  ll also.** be la
0ce0: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72 65  rger than the re
0cf0: 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  lease from which
0d00: 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e 20   it is derived. 
0d10: 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a   Either Y will.*
0d20: 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61  * be held consta
0d30: 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  nt and Z will be
0d40: 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20   incremented or 
0d50: 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69  else Y will be i
0d60: 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e  ncremented.** an
0d70: 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65  d Z will be rese
0d80: 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t to zero..**.**
0d90: 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33   Since version 3
0da0: 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f  .6.18, SQLite so
0db0: 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62 65  urce code has be
0dc0: 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  en stored in the
0dd0: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
0de0: 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73  p://www.fossil-s
0df0: 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20  cm.org/">Fossil 
0e00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0e10: 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74  nagement.** syst
0e20: 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51  em</a>.  ^The SQ
0e30: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d  LITE_SOURCE_ID m
0e40: 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74  acro evaluates t
0e50: 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68  o.** a string wh
0e60: 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20 61  ich identifies a
0e70: 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65 63   particular chec
0e80: 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a  k-in of SQLite.*
0e90: 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e  * within its con
0ea0: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
0eb0: 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e  ement system.  ^
0ec0: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  The SQLITE_SOURC
0ed0: 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63  E_ID.** string c
0ee0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 65  ontains the date
0ef0: 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65   and time of the
0f00: 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20   check-in (UTC) 
0f10: 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68  and an SHA1.** h
0f20: 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72  ash of the entir
0f30: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a  e source tree..*
0f40: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
0f50: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0f60: 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  on()],.** [sqlit
0f70: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
0f80: 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65  mber()], [sqlite
0f90: 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a  3_sourceid()],.*
0fa0: 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  * [sqlite_versio
0fb0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
0fc0: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
0fd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
0fe0: 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20  _VERSION        
0ff0: 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69  "--VERS--".#defi
1000: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
1010: 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49  N_NUMBER --VERSI
1020: 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66  ON-NUMBER--.#def
1030: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1040: 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55  E_ID      "--SOU
1050: 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a  RCE-ID--"../*.**
1060: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1070: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
1080: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
1090: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10a0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
10b0: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
10c0: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
10d0: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
10e0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
10f0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1100: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1110: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1120: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1130: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1140: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
1150: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
1160: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1170: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
1180: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
1190: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11a0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
11b0: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
11c0: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
11d0: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
11e0: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
11f0: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1200: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1210: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1220: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1230: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1240: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
1250: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
1260: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
1270: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
1280: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
1290: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12a0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
12b0: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
12c0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
12d0: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
12e0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
12f0: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1300: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1310: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1320: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1330: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1340: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
1350: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
1360: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
1370: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1380: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1390: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13a0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
13b0: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
13c0: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
13d0: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
13e0: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
13f0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1400: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1410: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1420: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1430: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1440: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
1450: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
1460: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
1470: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
1480: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1490: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14a0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
14b0: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
14c0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
14d0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
14e0: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
14f0: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1500: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1510: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1520: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1530: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1540: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
1550: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
1560: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
1570: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
1580: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
1590: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15a0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
15b0: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
15c0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
15d0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
15e0: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
15f0: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1600: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1610: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1620: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ()]..*/.SQLITE_E
1630: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72  XTERN const char
1640: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
1650: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  [];.const char *
1660: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1670: 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20  on(void);.const 
1680: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1690: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e  urceid(void);.in
16a0: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
16b0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
16c0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16d0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
16e0: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
16f0: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1700: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1710: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1720: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1730: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
1740: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
1750: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
1760: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
1770: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
1780: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
1790: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
17a0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
17b0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
17c0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
17d0: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
17e0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
17f0: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1800: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1810: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1820: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1830: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
1840: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
1850: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
1860: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
1870: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
1880: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
1890: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
18a0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
18b0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
18c0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
18d0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
18e0: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
18f0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1900: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1910: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1920: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1930: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1940: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1950: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
1960: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
1970: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
1980: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
1990: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
19a0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
19b0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
19c0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
19d0: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
19e0: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
19f0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1a00: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1a10: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1a20: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1a30: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1a40: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1a50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1a60: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1a70: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1a80: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1a90: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1aa0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1ab0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1ac0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1ad0: 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65  DIAGS.int sqlite
1ae0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1af0: 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20  used(const char 
1b00: 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73  *zOptName);.cons
1b10: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1b20: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b30: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66  t(int N);.#endif
1b40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b50: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1b60: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1b70: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a  Threadsafe.**.**
1b80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68   ^The sqlite3_th
1b90: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
1ba0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ion returns zero
1bb0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
1bc0: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  ** SQLite was co
1bd0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1be0: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65  xing code omitte
1bf0: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  d due to the.** 
1c00: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1c10: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  FE] compile-time
1c20: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65   option being se
1c30: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51  t to 0..**.** SQ
1c40: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70  Lite can be comp
1c50: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74  iled with or wit
1c60: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57  hout mutexes.  W
1c70: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  hen.** the [SQLI
1c80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43  TE_THREADSAFE] C
1c90: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1ca0: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d  cro is 1 or 2, m
1cb0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1cc0: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1cd0: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1ce0: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
1cf0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d00: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
1d10: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
1d20: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
1d30: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
1d40: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
1d50: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
1d60: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
1d70: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
1d80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
1d90: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
1da0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
1db0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1dc0: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1dd0: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1de0: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1df0: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
1e00: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
1e10: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
1e20: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
1e30: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
1e40: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
1e50: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65   ^The default be
1e60: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
1e70: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
1e80: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
1e90: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1ea0: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c   used by an appl
1eb0: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20  ication to make 
1ec0: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1ed0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
1ee0: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69  te that it is li
1ef0: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61  nking against wa
1f00: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
1f10: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73  ** the desired s
1f20: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53  etting of the [S
1f30: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f40: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54  ] macro..**.** T
1f50: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  his interface on
1f60: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68  ly reports on th
1f70: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
1f80: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20  utex setting.** 
1f90: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1fa0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e  HREADSAFE] flag.
1fb0: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
1fc0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
1fd0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fe0: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d  E=1 or =2 then m
1ff0: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
2000: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
2010: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
2020: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
2030: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
2040: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2050: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
2060: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
2070: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2080: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
2090: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
20a0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
20b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
20c0: 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75  EX].  ^(The retu
20d0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a  rn value of the.
20e0: 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  ** sqlite3_threa
20f0: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
2100: 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20   shows only the 
2110: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
2120: 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61  ting of.** threa
2130: 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e  d safety, not an
2140: 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67  y run-time chang
2150: 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74 69  es to that setti
2160: 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71  ng made by.** sq
2170: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20  lite3_config(). 
2180: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2190: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
21a0: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68   from sqlite3_th
21b0: 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73  readsafe().** is
21c0: 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61   unchanged by ca
21d0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
21e0: 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  onfig().)^.**.**
21f0: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
2200: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65  ing mode] docume
2210: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
2220: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
2230: 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  on..*/.int sqlit
2240: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f  e3_threadsafe(vo
2250: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
2260: 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
2270: 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65  onnection Handle
2280: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
2290: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22a0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
22b0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
22c0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
22d0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
22e0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
22f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
2300: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
2310: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
2320: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
2330: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
2340: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
2350: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
2360: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
2370: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
2380: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
2390: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
23a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
23b0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
23c0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
23d0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
23e0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
23f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2400: 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73  se_v2()] are its
2410: 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54   destructors.  T
2420: 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74  here are many ot
2430: 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  her.** interface
2440: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2450: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2460: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2470: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2480: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2490: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
24a0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
24b0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
24c0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
24d0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
24e0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24f0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
2500: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
2510: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2520: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2530: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2540: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2550: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2560: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2570: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2580: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
2590: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
25a0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
25b0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
25c0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
25d0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
25e0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
25f0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
2600: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
2610: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2620: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2630: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2640: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2650: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2660: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2670: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2680: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
2690: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26a0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
26b0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
26c0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
26d0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
26e0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
26f0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
2700: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2710: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2720: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2730: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2740: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2750: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2760: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2770: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2780: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
2790: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
27a0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
27b0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
27c0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
27d0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
27e0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
27f0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
2800: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
2810: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2820: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2830: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2840: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2850: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2860: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2870: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2880: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2890: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
28a0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
28b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
28c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
28d0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
28e0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
28f0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
2900: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
2910: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2920: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2930: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2940: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2950: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2960: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2970: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2980: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2990: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
29a0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
29b0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
29c0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
29d0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
29e0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
29f0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2a00: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
2a10: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2a20: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2a30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2a40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2a50: 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73  se_v2() routines
2a60: 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73   are destructors
2a70: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  .** for the [sql
2a80: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ite3] object..**
2a90: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
2aa0: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73  e3_close() and s
2ab0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2ac0: 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  ) return [SQLITE
2ad0: 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b  _OK] if.** the [
2ae0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2af0: 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  is successfully 
2b00: 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c  destroyed and al
2b10: 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  l associated.** 
2b20: 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 65  resources are de
2b30: 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  allocated..**.**
2b40: 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
2b50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2b60: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2b70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2b80: 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2b90: 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  ts or unfinished
2ba0: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2bb0: 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c  objects then sql
2bc0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20  ite3_close().** 
2bd0: 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64  will leave the d
2be0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2bf0: 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75  on open and retu
2c00: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
2c10: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
2c20: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63  _close_v2() is c
2c30: 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e  alled with unfin
2c40: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 20  alized prepared 
2c50: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e  statements.** an
2c60: 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20  d/or unfinished 
2c70: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c  sqlite3_backups,
2c80: 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
2c90: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  se connection be
2ca0: 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73  comes.** an unus
2cb0: 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68  able "zombie" wh
2cc0: 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ich will automat
2cd0: 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f  ically be deallo
2ce0: 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a  cated when the.*
2cf0: 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20  * last prepared 
2d00: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e  statement is fin
2d10: 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61  alized or the la
2d20: 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  st sqlite3_backu
2d30: 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64  p is.** finished
2d40: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  .  The sqlite3_c
2d50: 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66  lose_v2() interf
2d60: 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ace is intended 
2d70: 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20  for use with.** 
2d80: 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74  host languages t
2d90: 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65 20  hat are garbage 
2da0: 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77  collected, and w
2db0: 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20 69  here the order i
2dc0: 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72  n which.** destr
2dd0: 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65  uctors are calle
2de0: 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a  d is arbitrary..
2df0: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
2e00: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
2e10: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2e20: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
2e30: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2e40: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2e50: 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73  lob_close | clos
2e60: 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e  e] all [BLOB han
2e70: 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b  dles], and .** [
2e80: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66  sqlite3_backup_f
2e90: 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20  inish | finish] 
2ea0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  all [sqlite3_bac
2eb0: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73  kup] objects ass
2ec0: 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
2ed0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2ee0: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2ef0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2f00: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
2f10: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
2f20: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  ose_v2() is call
2f30: 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73  ed on a [databas
2f40: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
2f50: 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20  at still has.** 
2f60: 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65  outstanding [pre
2f70: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2f80: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ], [BLOB handles
2f90: 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71  ], and/or.** [sq
2fa0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2fb0: 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 65  jects then it re
2fc0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
2fd0: 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f  ] and the deallo
2fe0: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73  cation.** of res
2ff0: 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72  ources is deferr
3000: 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72  ed until all [pr
3010: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3020: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3030: 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  s],.** and [sqli
3040: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
3050: 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73  cts are also des
3060: 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  troyed..**.** ^I
3070: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  f an [sqlite3] o
3080: 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79  bject is destroy
3090: 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73  ed while a trans
30a0: 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a  action is open,.
30b0: 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ** the transacti
30c0: 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  on is automatica
30d0: 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  lly rolled back.
30e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72  .**.** The C par
30f0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
3100: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64  e3_close(C)] and
3110: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
3120: 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  v2(C)].** must b
3130: 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a  e either a NULL.
3140: 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e  ** pointer or an
3150: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3160: 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e  t pointer obtain
3170: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
3180: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
3190: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
31a0: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
31b0: 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
31c0: 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63  not previously c
31d0: 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69  losed..** ^Calli
31e0: 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  ng sqlite3_close
31f0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c  () or sqlite3_cl
3200: 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20  ose_v2() with a 
3210: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
3220: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61  argument is a ha
3230: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f  rmless no-op..*/
3240: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f  .int sqlite3_clo
3250: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e  se(sqlite3*);.in
3260: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  t sqlite3_close_
3270: 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  v2(sqlite3*);../
3280: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
3290: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
32a0: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
32b0: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
32c0: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
32d0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
32e0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
32f0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
3300: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
3310: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
3320: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
3330: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
3340: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
3350: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
3360: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
3370: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
3380: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
3390: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
33a0: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
33b0: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
33c0: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
33d0: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
33e0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
33f0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
3400: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
3410: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
3420: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
3430: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
3440: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
3450: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3460: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3470: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3480: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3490: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
34a0: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
34b0: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
34c0: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
34d0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
34e0: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
34f0: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
3500: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
3510: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
3520: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
3530: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
3540: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
3550: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3560: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3570: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3580: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3590: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
35a0: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
35b0: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
35c0: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
35d0: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
35e0: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
35f0: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
3600: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
3610: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3620: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67  s relayed throug
3630: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67  h to the 1st arg
3640: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a  ument of each.**
3650: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61   callback invoca
3660: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63  tion.  ^If the c
3670: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  allback pointer 
3680: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3690: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ).** is NULL, th
36a0: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69  en no callback i
36b0: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61  s ever invoked a
36c0: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61  nd result rows a
36d0: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a  re.** ignored..*
36e0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  *.** ^If an erro
36f0: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65  r occurs while e
3700: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51  valuating the SQ
3710: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
3720: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  sed into.** sqli
3730: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e  te3_exec(), then
3740: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
3750: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d  e current statem
3760: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a  ent stops and.**
3770: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74   subsequent stat
3780: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70  ements are skipp
3790: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68  ed.  ^If the 5th
37a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
37b0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
37c0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
37d0: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
37e0: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
37f0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
3800: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
3810: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
3820: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  d passed back th
3830: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
3840: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61  rameter..** To a
3850: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  void memory leak
3860: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  s, the applicati
3870: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  on should invoke
3880: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3890: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65  ].** on error me
38a0: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65  ssage strings re
38b0: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
38c0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
38d0: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65   of.** of sqlite
38e0: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74  3_exec() after t
38f0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
3900: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f   string is no lo
3910: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20  nger needed..** 
3920: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
3930: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3940: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3950: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72  ULL and no error
3960: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e  s.** occur, then
3970: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3980: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72  sets the pointer
3990: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61   in its 5th para
39a0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c  meter to.** NULL
39b0: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
39c0: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  g..**.** ^If an 
39d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
39e0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
39f0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71  non-zero, the sq
3a00: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3a10: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
3a20: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74  SQLITE_ABORT wit
3a30: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  hout invoking th
3a40: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e  e callback again
3a50: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20   and.** without 
3a60: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73  running any subs
3a70: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3a80: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
3a90: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  e 2nd argument t
3aa0: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
3ab0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75  ec() callback fu
3ac0: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a  nction is the.**
3ad0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
3ae0: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
3af0: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75  .  ^The 3rd argu
3b00: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3b10: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61  te3_exec().** ca
3b20: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
3b30: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3b40: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e  o strings obtain
3b50: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a  ed as if from.**
3b60: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3b70: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f  _text()], one fo
3b80: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20  r each column.  
3b90: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f  ^If an element o
3ba0: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  f a.** result ro
3bb0: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  w is NULL then t
3bc0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
3bd0: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
3be0: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  for the.** sqlit
3bf0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3c00: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ck is a NULL poi
3c10: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20  nter.  ^The 4th 
3c20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
3c30: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3c40: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  ) callback is an
3c50: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3c60: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68  rs to strings wh
3c70: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72  ere each.** entr
3c80: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65  y represents the
3c90: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70   name of corresp
3ca0: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f  onding result co
3cb0: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64  lumn as obtained
3cc0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3cd0: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
3ce0: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
3cf0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
3d00: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3d10: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
3d20: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  r, a pointer.** 
3d30: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
3d40: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ng, or a pointer
3d50: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f   that contains o
3d60: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
3d70: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f  nd/or .** SQL co
3d80: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20  mments, then no 
3d90: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
3da0: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
3db0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
3dc0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e   is not changed.
3dd0: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69  .**.** Restricti
3de0: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ons:.**.** <ul>.
3df0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3e00: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73  ication must ins
3e10: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74  ure that the 1st
3e20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3e30: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3e40: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20       is a valid 
3e50: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  and open [databa
3e60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
3e70: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3e80: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3e90: 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61   close the [data
3ea0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
3eb0: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
3ec0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61        the 1st pa
3ed0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3ee0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
3ef0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3f00: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c  s running..** <l
3f10: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f20: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69  on must not modi
3f30: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  fy the SQL state
3f40: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64  ment text passed
3f50: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68   into.**      th
3f60: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3f70: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3f80: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
3f90: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
3fa0: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69  g..** </ul>.*/.i
3fb0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
3fc0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3ff0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
4000: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
4010: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
4040: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4050: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4060: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4070: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4080: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4090: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
40c0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
40d0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
40e0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
4110: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
4120: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
4130: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
4140: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4150: 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64  RDS: {result cod
4160: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
4170: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65  *.** Many SQLite
4180: 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
4190: 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73  n an integer res
41a0: 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68  ult code from th
41b0: 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68  e set shown.** h
41c0: 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ere in order to 
41d0: 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73 73  indicate success
41e0: 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a   or failure..**.
41f0: 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64  ** New error cod
4200: 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
4210: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
4220: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
4230: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65  .** See also: [e
4240: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4250: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d  ode definitions]
4260: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4270: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20  TE_OK           
4280: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75  0   /* Successfu
4290: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62  l result */./* b
42a0: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f  eginning-of-erro
42b0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69  r-codes */.#defi
42c0: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  ne SQLITE_ERROR 
42d0: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51         1   /* SQ
42e0: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69  L error or missi
42f0: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ng database */.#
4300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4310: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f  TERNAL     2   /
4320: 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63  * Internal logic
4330: 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65   error in SQLite
4340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4350: 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20  TE_PERM         
4360: 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65  3   /* Access pe
4370: 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20  rmission denied 
4380: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4390: 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34  E_ABORT        4
43a0: 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72     /* Callback r
43b0: 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64  outine requested
43c0: 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65   an abort */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
43e0: 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20           5   /* 
43f0: 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  The database fil
4400: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
4410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4420: 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f  CKED       6   /
4430: 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65  * A table in the
4440: 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63   database is loc
4450: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4460: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20  QLITE_NOMEM     
4470: 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c     7   /* A mall
4480: 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23  oc() failed */.#
4490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
44a0: 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f  ADONLY     8   /
44b0: 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69  * Attempt to wri
44c0: 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61  te a readonly da
44d0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
44e0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55  e SQLITE_INTERRU
44f0: 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65  PT    9   /* Ope
4500: 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65  ration terminate
4510: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74  d by sqlite3_int
4520: 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69  errupt()*/.#defi
4530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  ne SQLITE_IOERR 
4540: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f        10   /* So
4550: 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20  me kind of disk 
4560: 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72  I/O error occurr
4570: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4580: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20  LITE_CORRUPT    
4590: 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74   11   /* The dat
45a0: 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65  abase disk image
45b0: 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f   is malformed */
45c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
45d0: 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20  NOTFOUND    12  
45e0: 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f   /* Unknown opco
45f0: 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69  de in sqlite3_fi
4600: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a  le_control() */.
4610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4620: 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20  ULL        13   
4630: 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69  /* Insertion fai
4640: 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61  led because data
4650: 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a  base is full */.
4660: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4670: 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20  ANTOPEN    14   
4680: 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65  /* Unable to ope
4690: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
46a0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
46b0: 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20  QLITE_PROTOCOL  
46c0: 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61    15   /* Databa
46d0: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
46e0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
46f0: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
4700: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
4710: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
4720: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4730: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
4740: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4750: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
4760: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4770: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
4780: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
4790: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
47a0: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
47b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
47c0: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
47d0: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
47e0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
47f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4800: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
4810: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
4820: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
4830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
4840: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
4850: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
4860: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
4880: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
4890: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
48a0: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
48b0: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
48c0: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
48d0: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
48e0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
48f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4900: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
4910: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
4920: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
4930: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
4940: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
4950: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
4960: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
4970: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
4980: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
4990: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
49a0: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
49b0: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
49c0: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
49d0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
49e0: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20   SQLITE_NOTICE  
49f0: 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69      27   /* Noti
4a00: 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73  fications from s
4a10: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4a20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
4a30: 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20  ARNING     28   
4a40: 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d  /* Warnings from
4a50: 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a   sqlite3_log() *
4a60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4a70: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
4a80: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4a90: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
4aa0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4ac0: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4ad0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4ae0: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4af0: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4b00: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4b10: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4b20: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4b30: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4b40: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
4b50: 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69  result code defi
4b60: 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49  nitions}.**.** I
4b70: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4b80: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4b90: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4ba0: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33   return one of 3
4bb0: 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65  0 integer.** [re
4bc0: 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f  sult codes].  Ho
4bd0: 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63  wever, experienc
4be0: 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74  e has shown that
4bf0: 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73   many of.** thes
4c00: 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  e result codes a
4c10: 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72  re too coarse-gr
4c20: 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20  ained.  They do 
4c30: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a  not provide as.*
4c40: 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69  * much informati
4c50: 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d  on about problem
4c60: 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  s as programmers
4c70: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e   might like.  In
4c80: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a   an effort to.**
4c90: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e   address this, n
4ca0: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
4cb0: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e   SQLite (version
4cc0: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72   3.3.8 and later
4cd0: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
4ce0: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
4cf0: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
4d00: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
4d10: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
4d20: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
4d30: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
4d40: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4d50: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
4d60: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
4d70: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
4d80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
4d90: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
4da0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
4db0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
4dc0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
4dd0: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
4de0: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
4df0: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
4e00: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
4e10: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
4e20: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
4e30: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
4e40: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
4e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
4e60: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4e70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4e80: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
4e90: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
4ea0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
4eb0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4ec0: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
4ed0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4ee0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
4ef0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f00: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
4f10: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
4f30: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4f40: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
4f50: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4f60: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
4f70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f80: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
4f90: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4fa0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
4fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4fc0: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
4fd0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4fe0: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
4ff0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5000: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
5010: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5020: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
5030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5040: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
5050: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5060: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
5070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5080: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
5090: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50a0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50c0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50e0: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
50f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5100: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5110: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5120: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5140: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5150: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5160: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
5190: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
51a0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
51b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
51c0: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
51d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51e0: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
51f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5200: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5210: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5220: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5240: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5250: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5260: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
5270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5280: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20  RR_SHMOPEN      
5290: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
52a0: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64  RR | (18<<8)).#d
52b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
52c0: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20  RR_SHMSIZE      
52d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
52e0: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64  RR | (19<<8)).#d
52f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5300: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20  RR_SHMLOCK      
5310: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5320: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64  RR | (20<<8)).#d
5330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5340: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20  RR_SHMMAP       
5350: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5360: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64  RR | (21<<8)).#d
5370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5380: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20  RR_SEEK         
5390: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53a0: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64  RR | (22<<8)).#d
53b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53c0: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20  RR_DELETE_NOENT 
53d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53e0: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64  RR | (23<<8)).#d
53f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5400: 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20  RR_MMAP         
5410: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5420: 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64  RR | (24<<8)).#d
5430: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5440: 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20  RR_GETTEMPPATH  
5450: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5460: 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64  RR | (25<<8)).#d
5470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5480: 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  RR_CONVPATH     
5490: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
54a0: 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64  RR | (26<<8)).#d
54b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
54c0: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
54d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
54e0: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
54f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5500: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
5510: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5520: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
5530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
5540: 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20  USY_SNAPSHOT    
5550: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
5560: 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29  USY   |  (2<<8))
5570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5580: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5590: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
55a0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
55b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
55c0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
55d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
55e0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
55f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5600: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5610: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5620: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5630: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5640: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43  QLITE_CANTOPEN_C
5650: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53  ONVPATH       (S
5660: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5670: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5680: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5690: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
56a0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
56b0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
56c0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
56d0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
56e0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
56f0: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5700: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5710: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5720: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5730: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5740: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5750: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5760: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5770: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5780: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5790: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
57a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
57b0: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
57c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57d0: 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20  _ABORT_ROLLBACK 
57e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
57f0: 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29  _ABORT | (2<<8))
5800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5810: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b  CONSTRAINT_CHECK
5820: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5830: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c  CONSTRAINT | (1<
5840: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5850: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5860: 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c  OMMITHOOK   (SQL
5870: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5880: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5890: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
58a0: 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20  NT_FOREIGNKEY   
58b0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
58c0: 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  NT | (3<<8)).#de
58d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
58e0: 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20  TRAINT_FUNCTION 
58f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5900: 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29  TRAINT | (4<<8))
5910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5920: 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55  CONSTRAINT_NOTNU
5930: 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  LL      (SQLITE_
5940: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c  CONSTRAINT | (5<
5950: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5960: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50  ITE_CONSTRAINT_P
5970: 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c  RIMARYKEY   (SQL
5980: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5990: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
59a0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
59b0: 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  NT_TRIGGER      
59c0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59d0: 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  NT | (7<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
59f0: 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20  TRAINT_UNIQUE   
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5a10: 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29  TRAINT | (8<<8))
5a20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a30: 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20  CONSTRAINT_VTAB 
5a40: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5a50: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c  CONSTRAINT | (9<
5a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52  ITE_CONSTRAINT_R
5a80: 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c  OWID        (SQL
5a90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5aa0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
5ab0: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5ac0: 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20  ECOVER_WAL      
5ad0: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5ae0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5af0: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5b00: 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20  ECOVER_ROLLBACK 
5b10: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5b20: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5b30: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f   SQLITE_WARNING_
5b40: 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20  AUTOINDEX       
5b50: 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20  (SQLITE_WARNING 
5b60: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5b70: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53  e SQLITE_AUTH_US
5b80: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ER              
5b90: 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20   (SQLITE_AUTH | 
5ba0: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5bb0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5bc0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5bd0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
5be0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
5bf0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
5c00: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
5c10: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5c20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5c30: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5c40: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5c50: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5c60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
5c70: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
5c80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c90: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
5ca0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5cb0: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5cc0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5cd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ce0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
5cf0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5d00: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
5d10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d30: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
5d40: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5d50: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
5d60: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d80: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
5d90: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
5da0: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
5db0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5dc0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
5dd0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5de0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
5df0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e00: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
5e10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5e20: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
5e30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e40: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
5e50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5e60: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
5e70: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5e80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e90: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
5ea0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5eb0: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
5ec0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5ed0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ee0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
5ef0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5f00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f20: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
5f30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5f40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f60: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
5f70: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
5f80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fa0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
5fb0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
5fc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5fd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fe0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5ff0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
6000: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6010: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6020: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
6030: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6040: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6060: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6070: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
6080: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6090: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
60a0: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
60b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
60c0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
60d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
60e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
60f0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
6100: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
6110: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6120: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6130: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6140: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6150: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6160: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6170: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6180: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6190: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
61a0: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
61b0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
61c0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
61d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
61e0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
61f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
6200: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6210: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
6220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6230: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6240: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6250: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
6260: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
6270: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
6280: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
6290: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
62a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
62b0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
62c0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
62d0: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
62e0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
62f0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
6300: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
6310: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
6320: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
6330: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6340: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6360: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
6370: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
6380: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6390: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
63a0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
63b0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
63c0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
63d0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
63e0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
63f0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
6400: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6410: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
6420: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
6430: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6440: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6450: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6460: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6470: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6480: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6490: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
64a0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
64b0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
64c0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
64d0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
64e0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
64f0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6500: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6510: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6520: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6530: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6540: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6550: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6560: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6570: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6580: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6590: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
65a0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
65b0: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
65c0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
65d0: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
65e0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
65f0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6600: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6610: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
6620: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
6630: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6640: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6650: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6660: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6670: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6680: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6690: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
66a0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
66b0: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
66c0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
66d0: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
66e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
66f0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6700: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
6710: 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  e that a file ca
6720: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
6730: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
6740: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
6750: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
6760: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6770: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
6780: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
6790: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
67a0: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
67b0: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
67c0: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
67d0: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ges..*/.#define 
67e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
67f0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
6800: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
6810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6820: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
6830: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6840: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6850: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6860: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
6870: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
6880: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6890: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
68a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
68b0: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
68c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
68d0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
68e0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
68f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6900: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
6910: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
6920: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6930: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6940: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6950: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
6960: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6970: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
6980: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
6990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
69a0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
69b0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
69c0: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
69d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
69e0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
69f0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
6a00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6a10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
6a20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6a30: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
6a40: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6a50: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
6a60: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
6a70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a80: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6a90: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
6aa0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6ab0: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
6ac0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  E              0
6ad0: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00002000../*.**
6ae0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
6af0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
6b00: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
6b10: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
6b20: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6b30: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
6b40: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6b50: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6b60: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6b70: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
6b80: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6b90: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6ba0: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6bb0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6bc0: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6bd0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6be0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
6bf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6c00: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
6c10: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6c20: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
6c30: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6c40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6c50: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6c60: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
6c70: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
6c80: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6c90: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6ca0: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6cb0: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6cc0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6cd0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
6ce0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
6cf0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
6d00: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6d10: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
6d20: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
6d30: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
6d40: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
6d50: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
6d60: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
6d70: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
6d80: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
6d90: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
6da0: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
6db0: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
6dc0: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
6dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6de0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
6df0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
6e00: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
6e10: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
6e20: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
6e30: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
6e40: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6e50: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
6e60: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
6e70: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
6e80: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
6e90: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
6ea0: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
6eb0: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
6ec0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6ed0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6ee0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
6ef0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
6f00: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6f10: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
6f20: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6f30: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
6f40: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
6f50: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
6f60: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
6f70: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
6f80: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
6f90: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
6fa0: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
6fb0: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
6fc0: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
6fd0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6fe0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6ff0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
7000: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
7010: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
7020: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
7030: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
7040: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
7050: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
7060: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
7070: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
7080: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
7090: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
70a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
70b0: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
70c0: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
70d0: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
70e0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
70f0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
7100: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
7110: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
7120: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
7130: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
7140: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
7150: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
7160: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
7170: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7180: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
7190: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
71a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
71b0: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
71c0: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
71d0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
71e0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
71f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7200: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
7210: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
7220: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
7230: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
7240: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
7250: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
7260: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
7270: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
7280: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
7290: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
72a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
72b0: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
72c0: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
72d0: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
72e0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
72f0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
7300: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
7310: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
7320: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
7330: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
7340: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7350: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
7360: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
7370: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
7380: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
7390: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
73a0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
73b0: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
73c0: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
73d0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
73e0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
73f0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
7400: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
7410: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
7420: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
7430: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7440: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
7450: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
7460: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
7470: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
7480: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7490: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
74a0: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
74b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
74c0: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
74d0: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
74e0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
74f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7500: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
7510: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
7520: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
7530: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
7540: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
7550: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
7560: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
7570: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
7580: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
7590: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
75a0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
75b0: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
75c0: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
75d0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
75e0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
75f0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7600: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
7610: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
7620: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
7630: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7640: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
7650: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
7660: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
7670: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7680: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
7690: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
76a0: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
76b0: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
76c0: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
76d0: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
76e0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
76f0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
7700: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7710: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
7720: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7730: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
7740: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
7750: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7760: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
7770: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
7780: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
7790: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
77a0: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
77b0: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
77c0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
77d0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
77e0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
77f0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
7800: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
7810: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
7820: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
7830: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
7840: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
7850: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
7860: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
7870: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
7880: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
7890: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
78a0: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
78b0: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
78c0: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
78d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
78e0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
78f0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
7900: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
7910: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7920: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
7930: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7940: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
7950: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
7960: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
7970: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
7980: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
7990: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
79a0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
79b0: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
79c0: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
79d0: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
79e0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
79f0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
7a00: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
7a10: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
7a20: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
7a30: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
7a40: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
7a50: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
7a60: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
7a70: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
7a80: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7a90: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7aa0: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7ab0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7ac0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7ad0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
7ae0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
7af0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
7b00: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7b10: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
7b20: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
7b30: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
7b40: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7b50: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
7b60: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
7b70: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
7b80: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7b90: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7ba0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7bb0: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7bc0: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7bd0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
7be0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
7bf0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
7c00: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
7c10: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
7c20: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
7c30: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
7c40: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7c50: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
7c60: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
7c70: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
7c80: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7c90: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
7ca0: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
7cb0: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
7cc0: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
7cd0: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
7ce0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
7cf0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
7d00: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
7d10: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
7d20: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
7d30: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
7d40: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
7d50: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
7d60: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f  * A [file contro
7d70: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74  l opcodes | list
7d80: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7d90: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7da0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7db0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7dc0: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7dd0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7de0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7df0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7e00: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
7e10: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
7e20: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7e30: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
7e40: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
7e50: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
7e60: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7e70: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7e80: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7e90: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7ea0: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7eb0: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7ec0: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7ed0: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7ee0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7ef0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7f00: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
7f10: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
7f20: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
7f30: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
7f40: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
7f50: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
7f60: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
7f70: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
7f80: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
7f90: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
7fa0: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
7fb0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
7fc0: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7fd0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7fe0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7ff0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
8000: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8010: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
8020: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8030: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
8040: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8050: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
8060: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8070: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
8080: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8090: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
80a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
80b0: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
80c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
80d0: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
80e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
80f0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
8100: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
8110: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
8120: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8130: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
8140: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8150: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8160: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
8170: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
8180: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
8190: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
81a0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
81b0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
81c0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
81d0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
81e0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
81f0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
8200: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
8210: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
8220: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
8230: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
8240: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
8250: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8260: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
8270: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
8280: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
8290: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
82a0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
82b0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
82c0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
82d0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
82e0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
82f0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
8300: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
8310: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
8320: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
8330: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
8340: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
8350: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
8360: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
8370: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
8380: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
8390: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
83a0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
83b0: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
83c0: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
83d0: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
83e0: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
83f0: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
8400: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
8410: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
8420: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
8430: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
8440: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
8450: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
8460: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
8470: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
8480: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
8490: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
84a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
84b0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
84c0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
84d0: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
84e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
84f0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
8500: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
8510: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8520: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
8530: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
8540: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8550: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8560: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
8570: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8580: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
8590: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
85a0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
85b0: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
85c0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
85d0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
85e0: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
85f0: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
8600: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
8610: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
8620: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
8630: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8640: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
8650: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
8660: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
8670: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
8680: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8690: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
86a0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
86b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
86c0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
86d0: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
86e0: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
86f0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
8700: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
8710: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
8720: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
8730: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
8740: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
8750: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
8760: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8770: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8780: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
8790: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
87a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
87b0: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
87c0: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
87d0: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
87e0: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
87f0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
8800: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
8810: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
8820: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
8830: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8840: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
8850: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8860: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
8870: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8880: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8890: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e  ersion 2 */.  in
88a0: 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69  t (*xFetch)(sqli
88b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
88c0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
88d0: 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a  int iAmt, void *
88e0: 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  *pp);.  int (*xU
88f0: 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  nfetch)(sqlite3_
8900: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8910: 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64  nt64 iOfst, void
8920: 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f   *p);.  /* Metho
8930: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8940: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  id for version 3
8950: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
8960: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
8970: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
8980: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
8990: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
89a0: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
89b0: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
89c0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
89d0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
89e0: 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72  des} {file contr
89f0: 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a  ol opcode}.**.**
8a00: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
8a10: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
8a20: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
8a30: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8a40: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
8a50: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8a60: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
8a70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8a80: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
8a90: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
8aa0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8ab0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
8ac0: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
8ad0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
8ae0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
8af0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
8b00: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
8b10: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
8b20: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
8b30: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
8b40: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
8b50: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8b60: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
8b70: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
8b80: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
8b90: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
8ba0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
8bb0: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
8bc0: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
8bd0: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
8be0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
8bf0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
8c00: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
8c10: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
8c20: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
8c30: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
8c40: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
8c50: 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ..** <ul>.** <li
8c60: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8c70: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
8c80: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8c90: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
8ca0: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
8cb0: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
8cc0: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
8cd0: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
8ce0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
8cf0: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
8d00: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
8d10: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
8d20: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
8d30: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
8d40: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
8d50: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
8d60: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
8d70: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
8d80: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
8d90: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
8da0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
8db0: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
8dc0: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
8dd0: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
8de0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
8df0: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
8e00: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
8e10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8e20: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  K_SIZE]].** The 
8e30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
8e40: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
8e50: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
8e60: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
8e70: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
8e80: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
8e90: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
8ea0: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
8eb0: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
8ec0: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
8ed0: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
8ee0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8ef0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
8f00: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
8f10: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
8f20: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
8f30: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
8f40: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
8f50: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
8f60: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
8f70: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
8f80: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
8f90: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
8fa0: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
8fb0: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
8fc0: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
8fd0: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
8fe0: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
8ff0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
9000: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9010: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9020: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
9030: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9040: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
9050: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
9060: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
9070: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9080: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
9090: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
90a0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
90b0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
90c0: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
90d0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
90e0: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
90f0: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
9100: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
9110: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9120: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
9130: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20  OMITTED]].** No 
9140: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a  longer in use..*
9150: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9160: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a  E_FCNTL_SYNC]].*
9170: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9180: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65  NTL_SYNC] opcode
9190: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
91a0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
91b0: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74  te and.** sent t
91c0: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69  o the VFS immedi
91d0: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65  ately before the
91e0: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
91f0: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a   invoked on a.**
9200: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
9210: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69  escriptor. Or, i
9220: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9230: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  od is not invoke
9240: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68  d .** because th
9250: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69  e user has confi
9260: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74  gured SQLite wit
9270: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79  h .** [PRAGMA sy
9280: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
9290: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
92a0: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  FF] it is invoke
92b0: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f  d in place .** o
92c0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
92d0: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65  od. In most case
92e0: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61  s, the pointer a
92f0: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77  rgument passed w
9300: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65  ith.** this file
9310: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c  -control is NULL
9320: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
9330: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9340: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a  is being synced.
9350: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20  ** as part of a 
9360: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63  multi-database c
9370: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d  ommit, the argum
9380: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
9390: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
93a0: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
93b0: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74  ing the transact
93c0: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72  ions master-jour
93d0: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56  nal file name. V
93e0: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f  FSes that .** do
93f0: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
9400: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c  ignal should sil
9410: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9420: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9430: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c  ations .** shoul
9440: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
9450: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9460: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
9470: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
9480: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74   may .** disrupt
9490: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
94a0: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
94b0: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
94c0: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
94d0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
94e0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
94f0: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20  ASETWO]].** The 
9500: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
9510: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f  MMIT_PHASETWO] o
9520: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9530: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9540: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73   SQLite.** and s
9550: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61  ent to the VFS a
9560: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  fter a transacti
9570: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d  on has been comm
9580: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  itted immediatel
9590: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20  y.** but before 
95a0: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
95b0: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20  unlocked. VFSes 
95c0: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64  that do not need
95d0: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20   this signal.** 
95e0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
95f0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
9600: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
9610: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9620: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9630: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
9640: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
9650: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
9660: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70  srupt the .** op
9670: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
9680: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9690: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
96a0: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
96b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
96c0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
96d0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
96e0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
96f0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
9700: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
9710: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
9720: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
9730: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
9740: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
9750: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
9760: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
9770: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
9780: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
9790: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
97a0: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
97b0: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
97c0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
97d0: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
97e0: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
97f0: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
9800: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
9810: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
9820: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
9830: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
9840: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
9850: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
9860: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
9870: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
9880: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
9890: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
98a0: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
98b0: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
98c0: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
98d0: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
98e0: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
98f0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
9900: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
9910: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
9920: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
9930: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
9940: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
9950: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
9960: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
9970: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
9980: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
9990: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
99a0: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
99b0: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
99c0: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
99d0: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
99e0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
99f0: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
9a00: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
9a10: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
9a20: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
9a30: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
9a40: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
9a50: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
9a60: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
9a70: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
9a80: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
9a90: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
9aa0: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
9ab0: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
9ac0: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
9ad0: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
9ae0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
9af0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
9b00: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9b10: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d  TL_PERSIST_WAL]]
9b20: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9b30: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9b40: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
9b50: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
9b60: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
9b70: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
9b80: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74  e Ahead Log] set
9b90: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
9ba0: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
9bb0: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
9bc0: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
9bd0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
9be0: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
9bf0: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
9c00: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
9c10: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
9c20: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
9c30: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
9c40: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
9c50: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
9c60: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
9c70: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
9c80: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
9c90: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
9ca0: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
9cb0: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
9cc0: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
9cd0: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
9ce0: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
9cf0: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
9d00: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
9d10: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9d20: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
9d30: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9d40: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
9d50: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
9d60: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
9d70: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
9d80: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
9d90: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
9da0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
9db0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
9dc0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9dd0: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
9de0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
9df0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
9e00: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
9e10: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
9e20: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
9e30: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
9e40: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
9e50: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
9e60: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
9e70: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
9e80: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
9e90: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
9ea0: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
9eb0: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
9ec0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9ed0: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9ee0: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
9ef0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9f00: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
9f10: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
9f20: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9f30: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
9f40: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
9f50: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
9f60: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
9f70: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
9f80: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
9f90: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
9fa0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9fb0: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
9fc0: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
9fd0: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
9fe0: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
9ff0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
a000: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a010: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
a020: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
a030: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
a040: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
a050: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
a060: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
a070: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
a080: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
a090: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
a0a0: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
a0b0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
a0c0: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
a0d0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
a0e0: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
a0f0: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
a100: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a110: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d  CNTL_OVERWRITE]]
a120: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a130: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
a140: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f  ] opcode is invo
a150: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66  ked by SQLite af
a160: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61  ter opening.** a
a170: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
a180: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  on to indicate t
a190: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69  hat, unless it i
a1a0: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f  s rolled back fo
a1b0: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e  r some.** reason
a1c0: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74  , the entire dat
a1d0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
a1e0: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  be overwritten b
a1f0: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a  y the current .*
a200: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  * transaction. T
a210: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56  his is used by V
a220: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73  ACUUM operations
a230: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a240: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a250: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ME]].** ^The [SQ
a260: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a270: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  ME] opcode can b
a280: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
a290: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a   the names of.**
a2a0: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20   all [VFSes] in 
a2b0: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20  the VFS stack.  
a2c0: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66  The names are of
a2d0: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61   all VFS shims a
a2e0: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  nd the.** final 
a2f0: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53  bottom-level VFS
a300: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74   are written int
a310: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
a320: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
a330: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
a340: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  d the result is 
a350: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68  stored in the ch
a360: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  ar* variable.** 
a370: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20  that the fourth 
a380: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71  parameter of [sq
a390: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a3a0: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e  ol()] points to.
a3b0: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69  .** The caller i
a3c0: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
a3d0: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
a3e0: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20  mory when done. 
a3f0: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20   As with.** all 
a400: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74  file-control act
a410: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e  ions, there is n
a420: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  o guarantee that
a430: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61   this will actua
a440: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69  lly.** do anythi
a450: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f  ng.  Callers sho
a460: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  uld initialize t
a470: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a480: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e to a NULL.** p
a490: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74  ointer in case t
a4a0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a4b0: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
a4c0: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d  ted.  This file-
a4d0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e  control.** is in
a4e0: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e  tended for diagn
a4f0: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a  ostic use only..
a500: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a510: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a520: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
a530: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
a540: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
a550: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
a560: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
a570: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
a580: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
a590: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
a5a0: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
a5b0: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
a5c0: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
a5d0: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
a5e0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
a5f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
a600: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
a610: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a620: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
a630: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
a640: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
a650: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
a660: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
a670: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
a680: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
a690: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
a6a0: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
a6b0: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
a6c0: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
a6d0: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
a6e0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
a6f0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
a700: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
a710: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
a720: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a730: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
a740: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
a750: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
a760: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
a770: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
a780: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
a790: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
a7a0: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
a7b0: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
a7c0: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
a7d0: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
a7e0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
a7f0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
a800: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
a810: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
a820: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
a830: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a840: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a850: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
a860: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
a870: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
a880: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
a890: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
a8a0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a8b0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
a8c0: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
a8d0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
a8e0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
a8f0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
a900: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
a910: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
a920: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
a930: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
a940: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
a950: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49  d statement.  ^I
a960: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
a970: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a980: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a990: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
a9a0: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
a9b0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
a9c0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a9d0: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
a9e0: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
a9f0: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
aa00: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
aa10: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
aa20: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
aa30: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
aa40: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
aa50: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
aa60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
aa70: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
aa80: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
aa90: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
aaa0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
aab0: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
aac0: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
aad0: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
aae0: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
aaf0: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ments..**.** <li
ab00: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
ab10: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a  BUSYHANDLER]].**
ab20: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ab30: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
ab40: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
ab50: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
ab60: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
ab70: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
ab80: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
ab90: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
aba0: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
abb0: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
abc0: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
abd0: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
abe0: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
abf0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
ac00: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
ac10: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
ac20: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
ac30: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
ac40: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
ac50: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
ac60: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
ac70: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
ac80: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
ac90: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
aca0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
acb0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
acc0: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
acd0: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
ace0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
acf0: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
ad00: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
ad10: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
ad20: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
ad30: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
ad40: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
ad50: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
ad60: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
ad70: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
ad80: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
ad90: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
ada0: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
adb0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
adc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
add0: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20  MPFILENAME]].** 
ade0: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e  ^Application can
adf0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c   invoke the [SQL
ae00: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
ae10: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e  LENAME] file-con
ae20: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20  trol.** to have 
ae30: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20  SQLite generate 
ae40: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  a.** temporary f
ae50: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68  ilename using th
ae60: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
ae70: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65   that is followe
ae80: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a  d to generate.**
ae90: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
aea0: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61  ames for TEMP ta
aeb0: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69  bles and other i
aec0: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54  nternal uses.  T
aed0: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  he.** argument s
aee0: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a  hould be a char*
aef0: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20  * which will be 
af00: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
af10: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74  filename.** writ
af20: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
af30: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
af40: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
af50: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68  .  The caller sh
af60: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b  ould.** invoke [
af70: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
af80: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f  on the result to
af90: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
afa0: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  leak..**.** <li>
afb0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  [[SQLITE_FCNTL_M
afc0: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  MAP_SIZE]].** Th
afd0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
afe0: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
aff0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b000: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20  to query or set 
b010: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e  the.** maximum n
b020: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74  umber of bytes t
b030: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64  hat will be used
b040: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70   for memory-mapp
b050: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61  ed I/O..** The a
b060: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
b070: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20  nter to a value 
b080: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f  of type sqlite3_
b090: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73  int64 that.** is
b0a0: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78   an advisory max
b0b0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b0c0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
b0d0: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20   to memory map. 
b0e0: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   The.** pointer 
b0f0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
b100: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75  ith the old valu
b110: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73  e.  The limit is
b120: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a   not changed if.
b130: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69  ** the value ori
b140: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20  ginally pointed 
b150: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
b160: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65  and so the curre
b170: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e  nt limit .** can
b180: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70   be queried by p
b190: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e  assing in a poin
b1a0: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76  ter to a negativ
b1b0: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a  e number.  This.
b1c0: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
b1d0: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
b1e0: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ly to implement 
b1f0: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
b200: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  e]..**.** <li>[[
b210: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b220: 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  CE]].** The [SQL
b230: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b240: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72   file control pr
b250: 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20  ovides advisory 
b260: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74  information.** t
b270: 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20  o the VFS about 
b280: 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20  what the higher 
b290: 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51  layers of the SQ
b2a0: 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64  Lite stack are d
b2b0: 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69  oing..** This fi
b2c0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b2d0: 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61  ed by some VFS a
b2e0: 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20  ctivity tracing 
b2f0: 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20  [shims]..** The 
b300: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65  argument is a ze
b310: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
b320: 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61  ring.  Higher la
b330: 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53  yers in the.** S
b340: 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20  QLite stack may 
b350: 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63  generate instanc
b360: 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  es of this file 
b370: 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68  control if.** th
b380: 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43  e [SQLITE_USE_FC
b390: 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69  NTL_TRACE] compi
b3a0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
b3b0: 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
b3c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b3d0: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a  NTL_HAS_MOVED]].
b3e0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b3f0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20  CNTL_HAS_MOVED] 
b400: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74  file control int
b410: 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75  erprets its argu
b420: 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69  ment as a.** poi
b430: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
b440: 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73  er and it writes
b450: 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20   a boolean into 
b460: 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70  that integer dep
b470: 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65  ending.** on whe
b480: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
b490: 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65  file has been re
b4a0: 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72  named, moved, or
b4b0: 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69   deleted since i
b4c0: 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f  t.** was first o
b4d0: 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  pened..**.** <li
b4e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b4f0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
b500: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b510: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
b520: 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65  T_HANDLE] opcode
b530: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
b540: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
b550: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
b560: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
b570: 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74  method to swap t
b580: 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77  he file handle w
b590: 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70  ith the one.** p
b5a0: 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
b5b0: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20   pArg argument. 
b5c0: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
b5d0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
b5e0: 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f  testing.** and o
b5f0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
b600: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
b610: 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65  QLITE_TEST is de
b620: 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75  fined..**.** </u
b630: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
b640: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
b650: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
b660: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
b670: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_GET_LOCKPROX
b680: 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20  YFILE           
b690: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
b6a0: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
b6b0: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
b6c0: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
b6d0: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
b6e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b6f0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
b700: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
b710: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
b720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b730: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
b740: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
b750: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b760: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
b770: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
b780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b790: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
b7a0: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
b7b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b7c0: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
b7d0: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
b7e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b7f0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
b800: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
b810: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b820: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
b830: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
b840: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b850: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
b860: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
b870: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
b880: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
b890: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
b8a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
b8b0: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
b8c0: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
b8d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b8e0: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
b8f0: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
b900: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b910: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
b920: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
b930: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
b940: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
b950: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    18.#define SQL
b960: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20  ITE_FCNTL_TRACE 
b970: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b980: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   19.#define SQLI
b990: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
b9a0: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
b9b0: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
b9c0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20  E_FCNTL_SYNC    
b9d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
b9e0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
b9f0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
ba00: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32  ASETWO        22
ba10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ba20: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
ba30: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a  HANDLE       23.
ba40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ba50: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
ba60: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
ba70: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
ba80: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
ba90: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
baa0: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
bab0: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
bac0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
bad0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
bae0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
baf0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
bb00: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
bb10: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
bb20: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
bb30: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
bb40: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
bb50: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
bb60: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
bb70: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
bb80: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
bb90: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
bba0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
bbb0: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
bbc0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
bbd0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
bbe0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
bbf0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
bc00: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
bc10: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
bc20: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
bc30: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
bc40: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
bc50: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
bc60: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
bc70: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
bc80: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
bc90: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
bca0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
bcb0: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
bcc0: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
bcd0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
bce0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
bcf0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
bd00: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
bd10: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
bd20: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
bd30: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
bd40: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
bd50: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
bd60: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
bd70: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
bd80: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
bd90: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
bda0: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
bdb0: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
bdc0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
bdd0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
bde0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
bdf0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
be00: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
be10: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
be20: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
be30: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
be40: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
be50: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
be60: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
be70: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
be80: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
be90: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
bea0: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
beb0: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
bec0: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
bed0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
bee0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
bef0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
bf00: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
bf10: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
bf20: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
bf30: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
bf40: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
bf50: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
bf60: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
bf70: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
bf80: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
bf90: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
bfa0: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
bfb0: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
bfc0: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
bfd0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
bfe0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
bff0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
c000: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
c010: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
c020: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
c030: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
c040: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
c050: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
c060: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
c070: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
c080: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
c090: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
c0a0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
c0b0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
c0c0: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
c0d0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
c0e0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
c0f0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
c100: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
c110: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
c120: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
c130: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
c140: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
c150: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
c160: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
c170: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
c180: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
c190: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
c1a0: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
c1b0: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
c1c0: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
c1d0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
c1e0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
c1f0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
c200: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
c210: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
c220: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
c230: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
c240: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
c250: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
c260: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
c270: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
c280: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
c290: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
c2a0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
c2b0: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
c2c0: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
c2d0: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
c2e0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
c2f0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
c300: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
c310: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
c320: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
c330: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
c340: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
c350: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
c360: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
c370: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
c380: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
c390: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
c3a0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
c3b0: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
c3c0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
c3d0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
c3e0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
c3f0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
c400: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
c410: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
c420: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
c430: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
c440: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
c450: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
c460: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
c470: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
c480: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
c490: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
c4a0: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
c4b0: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
c4c0: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
c4d0: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
c4e0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
c4f0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
c500: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
c510: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
c520: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
c530: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
c540: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
c550: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
c560: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
c570: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
c580: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
c590: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
c5a0: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
c5b0: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
c5c0: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
c5d0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
c5e0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
c5f0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
c600: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
c610: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
c620: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
c630: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
c640: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
c650: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
c660: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
c670: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
c680: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
c690: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
c6a0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
c6b0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
c6c0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
c6d0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
c6e0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
c6f0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
c700: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
c710: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
c720: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
c730: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
c740: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
c750: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
c760: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
c770: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
c780: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
c790: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
c7a0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c7b0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
c7c0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c7d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
c7e0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
c7f0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
c800: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
c810: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
c820: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
c830: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c840: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
c850: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c860: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
c870: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
c880: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
c890: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
c8a0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
c8b0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
c8c0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
c8d0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
c8e0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
c8f0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
c900: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
c910: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
c920: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
c930: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
c940: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
c950: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
c960: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
c970: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
c980: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
c990: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
c9a0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
c9b0: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
c9c0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
c9d0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
c9e0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
c9f0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
ca00: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
ca10: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
ca20: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
ca30: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
ca40: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
ca50: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
ca60: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
ca70: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
ca80: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
ca90: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
caa0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
cab0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
cac0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
cad0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
cae0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
caf0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
cb00: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
cb10: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
cb20: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
cb30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
cb40: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
cb50: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
cb60: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
cb70: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
cb80: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
cb90: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
cba0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
cbb0: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
cbc0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
cbd0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
cbe0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
cbf0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
cc00: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
cc10: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
cc20: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
cc30: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
cc40: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
cc50: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
cc60: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
cc70: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
cc80: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
cc90: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
cca0: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
ccb0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
ccc0: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
ccd0: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
cce0: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
ccf0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
cd00: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
cd10: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
cd20: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
cd30: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
cd40: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
cd50: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
cd60: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
cd70: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
cd80: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
cd90: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
cda0: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
cdb0: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
cdc0: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
cdd0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
cde0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
cdf0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
ce00: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
ce10: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
ce20: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
ce30: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
ce40: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
ce50: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
ce60: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
ce70: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
ce80: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
ce90: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
cea0: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
ceb0: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
cec0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
ced0: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
cee0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
cef0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
cf00: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
cf10: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
cf20: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
cf30: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
cf40: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
cf50: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
cf60: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
cf70: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
cf80: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
cf90: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
cfa0: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
cfb0: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
cfc0: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
cfd0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
cfe0: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
cff0: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
d000: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
d010: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
d020: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
d030: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
d040: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
d050: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
d060: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
d070: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
d080: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
d090: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
d0a0: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
d0b0: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
d0c0: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
d0d0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
d0e0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
d0f0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
d100: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
d110: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
d120: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
d130: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
d140: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
d150: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
d160: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
d170: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
d180: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
d190: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
d1a0: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
d1b0: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
d1c0: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
d1d0: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
d1e0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
d1f0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
d200: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
d210: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
d220: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
d230: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
d240: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
d250: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
d260: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
d270: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
d280: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
d290: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
d2a0: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
d2b0: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
d2c0: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
d2d0: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
d2e0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
d2f0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
d300: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
d310: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
d320: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
d330: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
d340: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
d350: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
d360: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
d370: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
d380: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
d390: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
d3a0: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
d3b0: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
d3c0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
d3d0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
d3e0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
d3f0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
d400: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
d410: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
d420: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
d430: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
d440: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
d450: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
d460: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
d470: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
d480: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
d490: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
d4a0: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
d4b0: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
d4c0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
d4d0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
d4e0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
d4f0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
d500: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
d510: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
d520: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
d530: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
d540: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
d550: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
d560: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
d570: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
d580: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
d590: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
d5a0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
d5b0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
d5c0: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
d5d0: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
d5e0: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
d5f0: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
d600: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
d610: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
d620: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
d630: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
d640: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
d650: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
d660: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
d670: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
d680: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
d690: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
d6a0: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
d6b0: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
d6c0: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
d6d0: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
d6e0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
d6f0: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
d700: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
d710: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
d720: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
d730: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
d740: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
d750: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
d760: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
d770: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
d780: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
d790: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
d7a0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
d7b0: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
d7c0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
d7d0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
d7e0: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
d7f0: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
d800: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
d810: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
d820: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
d830: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
d840: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
d850: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
d860: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
d870: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
d880: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
d890: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
d8a0: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
d8b0: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
d8c0: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
d8d0: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
d8e0: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
d8f0: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
d900: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
d910: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
d920: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
d930: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
d940: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
d950: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
d960: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
d970: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
d980: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
d990: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
d9a0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
d9b0: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
d9c0: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
d9d0: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
d9e0: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
d9f0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
da00: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
da10: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
da20: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
da30: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
da40: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
da50: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
da60: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
da70: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
da80: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
da90: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
daa0: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
dab0: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
dac0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
dad0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
dae0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
daf0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
db00: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
db10: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
db20: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
db30: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
db40: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
db50: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
db60: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
db70: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
db80: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
db90: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
dba0: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
dbb0: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
dbc0: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
dbd0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
dbe0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
dbf0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
dc00: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
dc10: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
dc20: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
dc30: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
dc40: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
dc50: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
dc60: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
dc70: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
dc80: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
dc90: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
dca0: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
dcb0: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
dcc0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
dcd0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
dce0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
dcf0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
dd00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
dd10: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
dd20: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
dd30: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
dd40: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
dd50: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
dd60: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
dd70: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
dd80: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
dd90: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
dda0: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
ddb0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ddc0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
ddd0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
dde0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
ddf0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
de00: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
de10: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
de20: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
de30: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
de40: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
de50: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
de60: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
de70: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
de80: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
de90: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
dea0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
deb0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
dec0: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
ded0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
dee0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
def0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
df00: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
df10: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
df20: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
df30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
df40: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
df50: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
df60: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
df70: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
df80: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
df90: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
dfa0: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
dfb0: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
dfc0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
dfd0: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
dfe0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
dff0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
e000: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
e010: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
e020: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
e030: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e040: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
e050: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
e060: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
e070: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
e080: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
e090: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
e0a0: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
e0b0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e0c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e0d0: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
e0e0: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
e0f0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
e100: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
e110: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e120: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
e130: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
e140: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
e150: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
e160: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e170: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
e180: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e190: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
e1a0: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
e1b0: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
e1c0: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
e1d0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
e1e0: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
e1f0: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
e200: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
e210: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
e220: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
e230: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
e240: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
e250: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
e260: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
e270: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
e280: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
e290: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
e2a0: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
e2b0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
e2c0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
e2d0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
e2e0: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
e2f0: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
e300: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
e310: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
e320: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
e330: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
e340: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e350: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
e360: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
e370: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
e380: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
e390: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
e3a0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
e3b0: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
e3c0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
e3d0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
e3e0: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
e3f0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
e400: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
e410: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
e420: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
e430: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
e440: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
e450: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
e460: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
e470: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e480: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
e490: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
e4a0: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
e4b0: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
e4c0: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
e4d0: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
e4e0: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
e4f0: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
e500: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
e510: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e520: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
e530: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
e540: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
e550: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
e560: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
e570: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
e580: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
e590: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
e5a0: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
e5b0: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
e5c0: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
e5d0: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
e5e0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
e5f0: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
e600: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
e610: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
e620: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
e630: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
e640: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
e650: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e660: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
e670: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
e680: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
e690: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
e6a0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
e6b0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
e6c0: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
e6d0: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
e6e0: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
e6f0: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
e700: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
e710: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
e720: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
e730: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
e740: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
e750: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
e760: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
e770: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
e780: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
e790: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
e7a0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
e7b0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
e7c0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
e7d0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
e7e0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
e7f0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
e800: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e810: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
e820: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
e830: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
e840: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
e850: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
e860: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
e870: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
e880: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
e890: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
e8a0: 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68   was given on th
e8b0: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
e8c0: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
e8d0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
e8e0: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
e8f0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
e900: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
e910: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
e920: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
e930: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
e940: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
e950: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
e960: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
e970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e980: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
e990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e9a0: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
e9b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e9c0: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
e9d0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
e9e0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
e9f0: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
ea00: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
ea10: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
ea20: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
ea30: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
ea40: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
ea50: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
ea60: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
ea70: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
ea80: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
ea90: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
eaa0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
eab0: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
eac0: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
ead0: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
eae0: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
eaf0: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
eb00: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
eb10: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
eb20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
eb30: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
eb40: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
eb50: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
eb60: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
eb70: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
eb80: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
eb90: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
eba0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
ebb0: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
ebc0: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
ebd0: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
ebe0: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
ebf0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
ec00: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
ec10: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
ec20: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
ec30: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
ec40: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
ec50: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
ec60: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
ec70: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
ec80: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
ec90: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
eca0: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
ecb0: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
ecc0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
ecd0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
ece0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
ecf0: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
ed00: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
ed10: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
ed20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ed30: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
ed40: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
ed50: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
ed60: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
ed70: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
ed80: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ed90: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
eda0: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
edb0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
edc0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
edd0: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
ede0: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
edf0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ee00: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
ee10: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
ee20: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
ee30: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
ee40: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
ee50: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ee60: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
ee70: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
ee80: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
ee90: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
eea0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
eeb0: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
eec0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
eed0: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
eee0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
eef0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ef00: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
ef10: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
ef20: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
ef30: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
ef40: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ef50: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
ef60: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
ef70: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
ef80: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
ef90: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
efa0: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
efb0: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
efc0: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
efd0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
efe0: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
eff0: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
f000: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
f010: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
f020: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f030: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
f040: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
f050: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
f060: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
f070: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
f080: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
f090: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f0a0: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
f0b0: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
f0c0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f0d0: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
f0e0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f0f0: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
f100: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
f110: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
f120: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
f130: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
f140: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f150: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
f160: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
f170: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
f180: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
f190: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
f1a0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
f1b0: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
f1c0: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
f1d0: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
f1e0: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
f1f0: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
f200: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
f210: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
f220: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
f230: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
f240: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
f250: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f260: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f270: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
f280: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
f290: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
f2a0: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
f2b0: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
f2c0: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
f2d0: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
f2e0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
f2f0: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
f300: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
f310: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
f320: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
f330: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f340: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
f350: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
f360: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
f370: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
f380: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
f390: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
f3a0: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
f3b0: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
f3c0: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
f3d0: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
f3e0: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
f3f0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
f400: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
f410: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
f420: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
f430: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
f440: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
f450: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
f460: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
f470: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
f480: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f490: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
f4a0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
f4b0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
f4c0: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
f4d0: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
f4e0: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
f4f0: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
f500: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
f510: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
f520: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
f530: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
f540: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
f550: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
f560: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
f570: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
f580: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
f590: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
f5a0: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
f5b0: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
f5c0: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
f5d0: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
f5e0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
f5f0: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
f600: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
f610: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
f620: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
f630: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
f640: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
f650: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
f660: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
f670: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
f680: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
f690: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
f6a0: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
f6b0: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
f6c0: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
f6d0: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
f6e0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
f6f0: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
f700: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
f710: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
f720: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
f730: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
f740: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
f750: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
f760: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
f770: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
f780: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
f790: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
f7a0: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
f7b0: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
f7c0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
f7d0: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
f7e0: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
f7f0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
f800: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
f810: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
f820: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
f830: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
f840: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
f850: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
f860: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
f870: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
f880: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
f890: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f8a0: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
f8b0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
f8c0: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
f8d0: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
f8e0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
f8f0: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
f900: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f910: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
f920: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f930: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
f940: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
f950: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
f960: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
f970: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
f980: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
f990: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
f9a0: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
f9b0: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
f9c0: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
f9d0: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
f9e0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
f9f0: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
fa00: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
fa10: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
fa20: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
fa30: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
fa40: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
fa50: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
fa60: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
fa70: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fa80: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
fa90: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
faa0: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
fab0: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
fac0: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
fad0: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
fae0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
faf0: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
fb00: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
fb10: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
fb20: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
fb30: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
fb40: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
fb50: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
fb60: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
fb70: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
fb80: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fb90: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
fba0: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
fbb0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
fbc0: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
fbd0: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
fbe0: 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
fbf0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
fc00: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
fc10: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
fc20: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
fc30: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
fc40: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
fc50: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
fc60: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
fc70: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
fc80: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
fc90: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
fca0: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
fcb0: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
fcc0: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
fcd0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
fce0: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
fcf0: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
fd00: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
fd10: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
fd20: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
fd30: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
fd40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
fd50: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
fd60: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
fd70: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
fd80: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
fd90: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
fda0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fdb0: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
fdc0: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
fdd0: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
fde0: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
fdf0: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
fe00: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
fe10: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
fe20: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
fe30: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
fe40: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
fe50: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
fe60: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
fe70: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
fe80: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
fe90: 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
fea0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
feb0: 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
fec0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fed0: 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
fee0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
fef0: 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
ff00: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
ff10: 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
ff20: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
ff30: 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
ff40: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
ff50: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
ff60: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
ff70: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
ff80: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
ff90: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ffa0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
ffb0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
ffc0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ffd0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
ffe0: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
fff0: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
10000 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
10010 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
10020 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
10030 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
10040 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
10050 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
10060 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
10070 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
10080 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10090 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
100a0 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
100b0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
100c0 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
100d0 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
100e0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
100f0 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
10100 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
10110 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
10120 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
10130 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
10140 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
10150 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
10160 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10170 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
10180 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10190 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
101a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
101b0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
101c0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
101d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
101e0 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
101f0 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
10200 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
10210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
10220 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
10230 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
10240 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10250 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
10260 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
10270 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
10280 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10290 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
102a0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
102b0 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
102c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
102d0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
102e0 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
102f0 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
10300 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10310 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
10320 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
10330 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
10340 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
10350 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
10360 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
10370 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
10380 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
10390 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
103a0 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
103b0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
103c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
103d0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
103e0 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
103f0 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
10400 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
10410 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
10420 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
10430 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
10440 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
10450 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
10460 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
10470 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
10480 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
10490 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
104a0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
104b0 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
104c0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
104d0 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
104e0 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
104f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10500 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
10510 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
10520 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
10530 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
10540 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10550 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
10560 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
10570 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
10580 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
10590 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
105a0 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
105b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
105c0 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
105d0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
105e0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
105f0 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
10600 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
10610 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10620 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
10630 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
10640 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
10650 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10660 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
10670 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
10680 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
10690 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
106a0 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
106b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
106c0 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
106d0 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
106e0 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
106f0 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
10700 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
10710 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
10720 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
10730 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
10740 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
10750 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
10760 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
10770 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
10780 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
10790 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
107a0 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
107b0 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
107c0 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
107d0 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
107e0 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
107f0 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
10800 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
10810 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
10820 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
10830 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
10840 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
10850 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
10860 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
10870 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
10880 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
10890 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
108a0 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
108b0 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
108c0 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
108d0 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
108e0 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
108f0 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
10900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
10910 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
10920 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
10930 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
10940 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
10950 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
10960 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
10970 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
10980 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
10990 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
109a0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
109b0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
109c0 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
109d0 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
109e0 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
109f0 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
10a00 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
10a10 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
10a20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
10a30 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
10a40 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
10a50 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
10a60 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
10a70 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
10a80 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
10a90 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
10aa0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
10ab0 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
10ac0 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
10ad0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
10ae0 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
10af0 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
10b00 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
10b10 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
10b20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
10b30 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
10b40 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
10b50 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
10b60 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
10b70 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
10b80 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
10b90 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
10ba0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
10bb0 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
10bc0 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
10bd0 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
10be0 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
10bf0 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
10c00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
10c10 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
10c20 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
10c30 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
10c40 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
10c50 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
10c60 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
10c70 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
10c80 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
10c90 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
10ca0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
10cb0 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
10cc0 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
10cd0 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
10ce0 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
10cf0 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
10d00 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
10d10 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
10d20 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
10d30 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
10d40 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
10d50 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
10d60 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
10d70 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
10d80 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
10d90 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10da0 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
10db0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
10dc0 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
10dd0 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
10de0 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
10df0 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
10e00 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
10e10 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
10e20 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
10e30 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
10e40 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
10e50 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
10e60 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
10e70 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
10e80 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
10e90 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
10ea0 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
10eb0 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
10ec0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
10ed0 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
10ee0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
10ef0 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
10f00 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
10f10 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
10f20 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
10f30 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
10f40 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
10f50 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
10f60 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
10f70 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
10f80 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
10f90 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
10fa0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10fb0 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
10fc0 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
10fd0 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
10fe0 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
10ff0 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
11000 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
11010 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
11020 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11030 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
11040 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
11050 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
11060 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
11070 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
11080 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
11090 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
110a0 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
110b0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
110c0 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
110d0 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
110e0 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
110f0 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
11100 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
11110 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
11120 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11130 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
11140 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
11150 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11160 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
11170 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
11180 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
11190 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
111a0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
111b0 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
111c0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
111d0 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
111e0 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
111f0 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
11200 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
11210 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
11220 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
11230 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
11240 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
11250 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
11260 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
11270 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
11280 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
11290 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
112a0 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
112b0 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
112c0 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
112d0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
112e0 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
112f0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
11300 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
11310 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
11320 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
11330 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
11340 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
11350 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
11360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
11370 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
11380 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
11390 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
113a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
113b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
113c0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
113d0 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
113e0 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
113f0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
11400 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
11410 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
11420 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
11430 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
11440 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
11450 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
11460 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11470 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
11480 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
11490 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
114a0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
114b0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
114c0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
114d0 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
114e0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
114f0 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
11500 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
11510 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
11520 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
11530 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
11540 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
11550 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
11560 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
11570 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
11580 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11590 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
115a0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
115b0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
115c0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
115d0 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
115e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
115f0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
11600 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
11610 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
11620 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
11630 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11640 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
11650 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
11660 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
11670 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
11680 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11690 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
116a0 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
116b0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
116c0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
116d0 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
116e0 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
116f0 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
11700 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
11710 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
11720 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
11730 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
11740 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11750 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
11760 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
11770 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
11780 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
11790 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
117a0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
117b0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
117c0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
117d0 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
117e0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
117f0 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
11800 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
11810 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
11820 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
11830 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11840 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
11850 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11860 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
11870 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
11880 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11890 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
118a0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
118b0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
118c0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
118d0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
118e0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
118f0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11900 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
11910 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11920 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
11930 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
11940 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
11950 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
11960 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11970 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
11980 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
11990 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
119a0 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
119b0 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
119c0 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
119d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
119e0 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
119f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11a00 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
11a10 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
11a20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
11a30 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
11a40 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
11a50 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
11a60 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
11a70 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
11a80 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
11a90 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
11aa0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11ab0 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
11ac0 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
11ad0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11ae0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11af0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11b00 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11b10 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11b20 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11b30 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
11b40 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
11b50 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
11b60 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11b70 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
11b80 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
11b90 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
11ba0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
11bb0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
11bc0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
11bd0 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
11be0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11bf0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11c00 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
11c10 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11c20 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
11c30 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
11c40 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
11c50 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
11c60 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
11c70 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
11c80 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
11c90 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
11ca0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
11cb0 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
11cc0 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
11cd0 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
11ce0 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
11cf0 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
11d00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
11d10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11d20 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
11d30 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
11d40 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
11d50 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
11d60 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11d70 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
11d80 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
11d90 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
11da0 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
11db0 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
11dc0 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
11dd0 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
11de0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11df0 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
11e00 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
11e10 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
11e20 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
11e30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
11e40 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
11e50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
11e60 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
11e70 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
11e80 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
11e90 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11ea0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11eb0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11ec0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11ed0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11ee0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
11ef0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
11f00 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
11f10 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
11f20 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
11f30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
11f40 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
11f50 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
11f60 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
11f70 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
11f80 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
11f90 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11fa0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
11fb0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11fc0 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
11fd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11fe0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
11ff0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
12000 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  NFIG_MALLOC opti
12010 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12020 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12030 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
12040 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
12050 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12060 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12070 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
12080 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
12090 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
120a0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
120b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
120c0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
120d0 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
120e0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
120f0 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12100 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12110 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
12120 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
12130 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
12140 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
12150 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12160 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12170 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
12180 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12190 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
121a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
121b0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
121c0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
121d0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
121e0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
121f0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
12200 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70  FIG_GETMALLOC op
12210 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12220 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12230 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
12240 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
12250 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12260 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
12270 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
12280 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12290 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
122a0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
122b0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
122c0 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
122d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
122e0 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
122f0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
12300 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
12310 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
12320 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
12330 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
12340 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
12350 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
12360 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
12370 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
12380 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
12390 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
123a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
123b0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
123c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
123d0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
123e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
123f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
12400 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74  MSTATUS option t
12410 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
12420 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
12430 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64  ,.** interpreted
12440 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
12450 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
12460 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
12470 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65  lection of.** me
12480 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12490 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
124a0 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
124b0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
124c0 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c  are.** disabled,
124d0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
124e0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
124f0 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
12500 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
12510 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
12520 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
12530 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
12540 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
12550 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
12560 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
12570 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
12580 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
12590 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
125a0 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
125b0 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
125c0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
125d0 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
125e0 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
125f0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
12600 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
12610 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
12620 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
12630 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
12640 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
12650 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
12660 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
12670 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12680 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12690 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
126a0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
126b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
126c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
126d0 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70  CRATCH option sp
126e0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
126f0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a   memory buffer.*
12700 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  * that SQLite ca
12710 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63  n use for scratc
12720 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65  h memory.  ^(The
12730 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
12740 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c  uments.** to SQL
12750 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12760 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  CH:  A pointer a
12770 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
12780 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
12790 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
127a0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
127b0 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
127c0 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
127d0 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
127e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
127f0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
12800 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
12810 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
12820 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20  s (N).)^.** The 
12830 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
12840 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72  ust be a pointer
12850 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
12860 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20  igned buffer.** 
12870 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
12880 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
12890 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
128a0 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74  l not use more t
128b0 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20  han one scratch 
128c0 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65  buffers per thre
128d0 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ad..** ^SQLite w
128e0 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73  ill never reques
128f0 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  t a scratch buff
12900 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
12910 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20  than 6.** times 
12920 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
12930 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53  e size..** ^If S
12940 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
12950 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
12960 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
12970 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
12980 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
12990 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
129a0 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
129b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
129c0 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
129d0 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
129e0 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a  ry needed.<p>.**
129f0 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69   ^When the appli
12a00 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20  cation provides 
12a10 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63  any amount of sc
12a20 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69  ratch memory usi
12a30 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  ng.** SQLITE_CON
12a40 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c  FIG_SCRATCH, SQL
12a50 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63  ite avoids unnec
12a60 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20  essary large.** 
12a70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c  [sqlite3_malloc|
12a80 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  heap allocations
12a90 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68  ]..** This can h
12aa0 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f  elp [Robson proo
12ab0 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79  f|prevent memory
12ac0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
12ad0 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61  ures] due to hea
12ae0 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69  p.** fragmentati
12af0 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79  on in low-memory
12b00 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
12b10 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
12b20 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12b30 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
12b40 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12b50 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
12b60 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
12b70 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
12b80 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  CHE option speci
12b90 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
12ba0 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74  mory buffer.** t
12bb0 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
12bc0 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  se for the datab
12bd0 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
12be0 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
12bf0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
12c00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
12c10 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
12c20 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
12c30 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
12c40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
12c50 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
12c60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
12c70 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
12c80 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
12c90 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20 63 6f  G_PCACHE2].** co
12ca0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12cb0 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  on..** ^There ar
12cc0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
12cd0 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
12ce0 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20  IG_PAGECACHE: A 
12cf0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d  pointer to.** 8-
12d00 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
12d10 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
12d20 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
12d30 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
12d40 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
12d50 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
12d60 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
12d70 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
12d80 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
12d90 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
12da0 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
12db0 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
12dc0 37 36 38 29 20 70 6c 75 73 20 73 6f 6d 65 20 65  768) plus some e
12dd0 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65  xtra bytes for e
12de0 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
12df0 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72  er.  ^The number
12e00 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20   of extra bytes 
12e10 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61  needed by the pa
12e20 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e  ge header.** can
12e30 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
12e40 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
12e50 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
12e60 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a  DRSZ] option .**
12e70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
12e80 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69  fig()]..** ^It i
12e90 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
12ea0 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
12eb0 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72  d memory,.** for
12ec0 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65   the sz paramete
12ed0 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74  r to be larger t
12ee0 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20  han necessary.  
12ef0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
12f00 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
12f10 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
12f20 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20  e aligned block 
12f30 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74 0a 2a  of memory that.*
12f40 2a 20 69 73 20 61 74 20 6c 65 61 73 74 20 73 7a  * is at least sz
12f50 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
12f60 72 79 2c 20 6f 74 68 65 72 77 69 73 65 20 73 75  ry, otherwise su
12f70 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
12f80 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
12f90 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  d..** ^SQLite wi
12fa0 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
12fb0 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
12fc0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12fd0 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
12fe0 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
12ff0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
13000 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
13010 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
13020 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
13030 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
13040 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
13050 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
13060 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
13070 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
13080 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
13090 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
130a0 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
130b0 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 3c   storage space.<
130c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
130d0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
130e0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
130f0 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
13100 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
13110 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70  E_CONFIG_HEAP op
13120 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
13130 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
13140 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53  uffer .** that S
13150 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66  QLite will use f
13160 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
13170 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
13180 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a  ocation needs.**
13190 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
131a0 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53  ovided for by [S
131b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
131c0 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51  ATCH] and.** [SQ
131d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
131e0 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20  CACHE]..** ^The 
131f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
13200 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  AP option is onl
13210 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53  y available if S
13220 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13230 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72  d.** with either
13240 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
13250 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c  MEMSYS3] or [SQL
13260 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
13270 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  S5] and returns.
13280 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
13290 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68  ] if invoked oth
132a0 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72  erwise..** ^Ther
132b0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
132c0 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
132d0 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20  CONFIG_HEAP:.** 
132e0 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
132f0 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
13300 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
13310 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
13320 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
13330 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
13340 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
13350 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
13360 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
13370 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
13380 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
13390 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
133a0 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
133b0 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
133c0 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
133d0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
133e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
133f0 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
13400 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
13410 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
13420 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
13430 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
13440 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
13450 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  LL then the alte
13460 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
13470 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
13480 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
13490 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
134a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
134b0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
134c0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
134d0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
134e0 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
134f0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
13500 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
13510 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
13520 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
13530 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a  l be undefined..
13540 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61  ** The minimum a
13550 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69  llocation size i
13560 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31  s capped at 2**1
13570 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61  2. Reasonable va
13580 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  lues.** for the 
13590 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
135a0 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35  on size are 2**5
135b0 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f   through 2**8.</
135c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
135d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
135e0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
135f0 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
13600 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
13610 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
13620 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13630 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13640 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f  which is a.** po
13650 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
13660 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
13670 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13680 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
13690 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
136a0 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61  pecifies alterna
136b0 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
136c0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
136d0 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70   be used.** in p
136e0 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72  lace the mutex r
136f0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
13700 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
13710 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
13720 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
13730 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
13740 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13750 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
13760 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
13770 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13780 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
13790 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
137a0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
137b0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
137c0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
137d0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
137e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
137f0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
13800 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
13810 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
13820 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
13830 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
13840 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13850 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
13860 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13870 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
13880 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
13890 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
138a0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
138b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
138c0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
138d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
138e0 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
138f0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13900 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13910 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
13920 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13930 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
13940 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13950 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13960 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13970 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13980 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
13990 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
139a0 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
139b0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
139c0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
139d0 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
139e0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
139f0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
13a00 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
13a10 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
13a20 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
13a30 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
13a40 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
13a50 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
13a60 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
13a70 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
13a80 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
13a90 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
13aa0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13ab0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
13ac0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13ad0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13ae0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
13af0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
13b00 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
13b10 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
13b20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
13b30 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
13b40 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
13b50 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13b60 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
13b70 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
13b80 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
13b90 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
13ba0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
13bb0 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
13bc0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13bd0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
13be0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13bf0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
13c00 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
13c10 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
13c20 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SIDE option take
13c30 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
13c40 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a  that determine.*
13c50 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69  * the default si
13c60 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20  ze of lookaside 
13c70 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b  memory on each [
13c80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13c90 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ion]..** The fir
13ca0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
13cb0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
13cc0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
13cd0 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
13ce0 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
13cf0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
13d00 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
13d10 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
13d20 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51  nection.)^  ^(SQ
13d30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
13d40 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68  ASIDE.** sets th
13d50 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  e <i>default</i>
13d60 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
13d70 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
13d80 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
13d90 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73  .** option to [s
13da0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
13db0 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20  ()] can be used 
13dc0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
13dd0 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69  okaside.** confi
13de0 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  guration on indi
13df0 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f  vidual connectio
13e00 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ns.)^ </dd>.**.*
13e10 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13e20 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  G_PCACHE2]] <dt>
13e30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13e40 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
13e50 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
13e60 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
13e70 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13e80 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
13e90 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
13ea0 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69  nter to an [sqli
13eb0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
13ec0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ds2] object.  Th
13ed0 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
13ee0 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72  ies.** the inter
13ef0 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d  face to a custom
13f00 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
13f10 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  ementation.)^.**
13f20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
13f30 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
13f40 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
13f50 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f  hods2] object.</
13f60 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13f70 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
13f80 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
13f90 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
13fa0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
13fb0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
13fc0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
13fd0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
13fe0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
13ff0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
14000 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69  nter to an [sqli
14010 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
14020 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ds2] object.  SQ
14030 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a  Lite copies of.*
14040 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61  * the current pa
14050 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
14060 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
14070 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64  t object.)^ </dd
14080 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14090 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64  _CONFIG_LOG]] <d
140a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
140b0 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
140c0 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   The SQLITE_CONF
140d0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73  IG_LOG option is
140e0 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
140f0 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a  re the SQLite.**
14100 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c   global [error l
14110 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51  og]..** (^The SQ
14120 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
14130 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
14140 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
14150 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
14160 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
14170 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
14180 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
14190 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
141a0 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
141b0 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
141c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
141d0 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
141e0 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
141f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
14200 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
14210 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
14220 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
14230 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
14240 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
14250 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
14260 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
14270 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
14280 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
14290 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
142a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
142b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
142c0 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
142d0 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
142e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
142f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
14300 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
14310 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
14320 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
14330 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
14340 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
14350 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
14360 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
14370 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
14380 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
14390 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
143a0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
143b0 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
143c0 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
143d0 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
143e0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
143f0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
14400 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
14410 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
14420 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
14430 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
14440 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
14450 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
14460 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
14470 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
14480 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
14490 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
144a0 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
144b0 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
144c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
144d0 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
144e0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
144f0 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
14500 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
14510 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
14520 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
14530 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
14540 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
14550 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
14560 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14570 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51  FIG_URI]] <dt>SQ
14580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a  LITE_CONFIG_URI.
14590 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c  ** <dd>^(The SQL
145a0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f  ITE_CONFIG_URI o
145b0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
145c0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
145d0 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66   type int..** If
145e0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
145f0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
14600 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
14610 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
14620 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74  er is zero,.** t
14630 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
14640 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
14650 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49  abled.)^ ^If URI
14660 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
14670 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64  bally.** enabled
14680 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20  , all filenames 
14690 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
146a0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
146b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
146c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
146d0 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65  n16()] or.** spe
146e0 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
146f0 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61  f [ATTACH] comma
14700 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  nds are interpre
14710 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67  ted as URIs, reg
14720 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68  ardless.** of wh
14730 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
14740 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
14750 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  I] flag is set w
14760 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
14770 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
14780 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74  s opened. ^If it
14790 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
147a0 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73  abled, filenames
147b0 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74   are.** only int
147c0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
147d0 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f   if the SQLITE_O
147e0 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20  PEN_URI flag is 
147f0 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  set when the.** 
14800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14810 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14820 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49  (By default, URI
14830 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
14840 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
14850 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
14860 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
14870 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
14880 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
14890 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
148a0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a  mbol defined.)^.
148b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
148c0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
148d0 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e  NDEX_SCAN]] <dt>
148e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
148f0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14900 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  N.** <dd>^The SQ
14910 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
14920 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
14930 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14940 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a  ingle integer.**
14950 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
14960 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
14970 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f  s a boolean in o
14980 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f  rder to enable o
14990 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  r disable.** the
149a0 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
149b0 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
149c0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e  l table scans in
149d0 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d   the query optim
149e0 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  izer..** ^The de
149f0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73  fault setting is
14a00 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62   determined.** b
14a10 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c  y the [SQLITE_AL
14a20 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  LOW_COVERING_IND
14a30 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65  EX_SCAN] compile
14a40 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72  -time option, or
14a50 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74   is "on".** if t
14a60 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  hat compile-time
14a70 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74   option is omitt
14a80 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69  ed..** The abili
14a90 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68  ty to disable th
14aa0 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
14ab0 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
14ac0 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a  ll table scans.*
14ad0 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d  * is because som
14ae0 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f  e incorrectly co
14af0 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69  ded legacy appli
14b00 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61  cations might ma
14b10 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65  lfunction.** whe
14b20 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  n the optimizati
14b30 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20  on is enabled.  
14b40 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62  Providing the ab
14b50 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61  ility to.** disa
14b60 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  ble the optimiza
14b70 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20  tion allows the 
14b80 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70  older, buggy app
14b90 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f  lication code to
14ba0 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74   work.** without
14bb0 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74   change even wit
14bc0 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  h newer versions
14bd0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
14be0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14bf0 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
14c00 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14c10 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
14c20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14c30 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
14c40 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a  NFIG_GETPCACHE.*
14c50 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74  * <dd> These opt
14c60 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74  ions are obsolet
14c70 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74  e and should not
14c80 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20   be used by new 
14c90 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72  code..** They ar
14ca0 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
14cb0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
14cc0 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e  bility but are n
14cd0 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f  ow no-ops..** </
14ce0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14cf0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
14d00 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
14d10 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a  _CONFIG_SQLLOG.*
14d20 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
14d30 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
14d40 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73  ble if sqlite is
14d50 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
14d60 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
14d70 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65  ABLE_SQLLOG] pre
14d80 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
14d90 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
14da0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
14db0 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
14dc0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
14dd0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
14de0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
14df0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
14e00 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
14e10 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
14e20 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
14e30 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
14e40 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
14e50 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
14e60 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
14e70 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
14e80 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
14e90 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
14ea0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
14eb0 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
14ec0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
14ed0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
14ee0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
14ef0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
14f00 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
14f10 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
14f20 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
14f30 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
14f40 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
14f50 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
14f60 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
14f70 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
14f80 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
14f90 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
14fa0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
14fb0 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
14fc0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
14fd0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
14fe0 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
14ff0 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
15000 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
15010 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
15020 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
15030 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
15040 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15050 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
15060 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
15070 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
15080 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
15090 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c  case.  An exampl
150a0 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a  e of using this.
150b0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
150c0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73   option can be s
150d0 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74  een in the "test
150e0 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63  _sqllog.c" sourc
150f0 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65  e file in.** the
15100 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74   canonical SQLit
15110 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f  e source tree.</
15120 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15130 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
15140 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
15150 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
15160 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c  SIZE.** <dd>^SQL
15170 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
15180 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36  SIZE takes two 6
15190 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73  4-bit integer (s
151a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61  qlite3_int64) va
151b0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  lues.** that are
151c0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61   the default mma
151d0 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68  p size limit (th
151e0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
151f0 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41  g for.** [PRAGMA
15200 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64   mmap_size]) and
15210 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c   the maximum all
15220 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c  owed mmap size l
15230 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  imit..** ^The de
15240 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61  fault setting ca
15250 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20  n be overridden 
15260 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65  by each database
15270 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e   connection usin
15280 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20  g.** either the 
15290 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
152a0 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62  e] command, or b
152b0 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  y using the.** [
152c0 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
152d0 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
152e0 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78  trol.  ^(The max
152f0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
15300 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62  p size.** will b
15310 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  e silently trunc
15320 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72  ated if necessar
15330 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65  y so that it doe
15340 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65  s not exceed the
15350 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
15360 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69   maximum mmap si
15370 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a  ze set by the.**
15380 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41   [SQLITE_MAX_MMA
15390 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d  P_SIZE] compile-
153a0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a  time option.)^.*
153b0 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67  * ^If either arg
153c0 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70  ument to this op
153d0 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65  tion is negative
153e0 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75  , then that argu
153f0 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67  ment is.** chang
15400 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c  ed to its compil
15410 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a  e-time default..
15420 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15430 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
15440 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
15450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15460 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64  2_HEAPSIZE.** <d
15470 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
15480 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15490 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  IZE option is on
154a0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
154b0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
154c0 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77  piled for Window
154d0 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  s with the [SQLI
154e0 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d  TE_WIN32_MALLOC]
154f0 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
15500 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e  acro.** defined.
15510 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   ^SQLITE_CONFIG_
15520 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74  WIN32_HEAPSIZE t
15530 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e  akes a 32-bit un
15540 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76  signed integer v
15550 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65  alue.** that spe
15560 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d  cifies the maxim
15570 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63  um size of the c
15580 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 20  reated heap..** 
15590 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dl>.**.** [[SQ
155a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
155b0 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64  HE_HDRSZ]].** <d
155c0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
155d0 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20  PCACHE_HDRSZ.** 
155e0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
155f0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
15600 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  RSZ option takes
15610 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
15620 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
15630 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
15640 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74  integer and writ
15650 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  es into that int
15660 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20  eger the number 
15670 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65  of extra.** byte
15680 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69  s per page requi
15690 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67  red for each pag
156a0 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e in [SQLITE_CON
156b0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
156c0 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ** The amount of
156d0 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71   extra space req
156e0 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65  uired can change
156f0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
15700 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74  e compiler,.** t
15710 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20  arget platform, 
15720 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
15730 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  on..** </dl>.*/.
15740 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15750 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
15760 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
15770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15780 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
15790 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
157a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
157b0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
157c0 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
157d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
157e0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
157f0 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
15800 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
15810 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
15820 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
15830 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
15840 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
15850 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
15860 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
15870 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
15880 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
15890 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
158a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
158b0 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
158c0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
158d0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
158e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
158f0 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
15900 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
15910 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
15920 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15930 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
15940 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
15950 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
15960 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
15970 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
15980 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
15990 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
159a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
159b0 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
159c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
159d0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
159e0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
159f0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
15a00 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
15a10 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
15a20 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
15a30 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
15a40 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
15a50 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
15a60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15a70 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
15a80 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
15a90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15aa0 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
15ab0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
15ac0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15ad0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
15ae0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
15af0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
15b00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
15b10 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
15b20 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
15b30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15b40 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
15b50 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
15b60 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
15b70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15b80 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
15b90 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
15ba0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
15bb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15bc0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
15bd0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
15be0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
15bf0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15c00 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
15c10 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
15c20 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
15c30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
15c40 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
15c50 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
15c60 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
15c70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15c80 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15c90 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20  APSIZE      23  
15ca0 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
15cb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15cc0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
15cd0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a  SZ        24  /*
15ce0 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 0a 2f 2a   int *psz */../*
15cf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
15d00 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
15d10 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
15d20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
15d30 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
15d40 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
15d50 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
15d60 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
15d70 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
15d80 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
15d90 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
15da0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
15db0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
15dc0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
15dd0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15de0 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
15df0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
15e00 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
15e10 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
15e20 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
15e30 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
15e40 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
15e50 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
15e60 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
15e70 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
15e80 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
15e90 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
15ea0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
15eb0 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
15ec0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
15ed0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
15ee0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
15ef0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
15f00 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
15f10 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
15f20 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
15f30 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
15f40 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
15f50 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
15f60 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
15f70 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
15f80 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
15f90 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
15fa0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
15fb0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
15fc0 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
15fd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
15fe0 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
15ff0 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
16000 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
16010 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
16020 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
16030 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
16040 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
16050 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
16060 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
16070 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
16080 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
16090 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
160a0 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
160b0 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
160c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
160d0 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
160e0 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
160f0 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
16100 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
16110 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
16120 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
16130 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
16140 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
16150 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
16160 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
16170 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
16180 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
16190 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
161a0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
161b0 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
161c0 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
161d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
161e0 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
161f0 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
16200 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
16210 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
16220 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
16230 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
16240 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
16250 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
16260 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
16270 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16280 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
16290 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
162a0 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
162b0 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
162c0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
162d0 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
162e0 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
162f0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
16300 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
16310 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
16320 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
16330 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16340 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
16350 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
16360 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
16370 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
16380 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
16390 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
163a0 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
163b0 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
163c0 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
163d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
163e0 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
163f0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
16400 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
16410 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
16420 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
16430 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
16440 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
16450 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
16460 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
16470 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
16480 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
16490 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
164a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
164b0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
164c0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
164d0 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
164e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
164f0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
16500 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
16510 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
16520 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
16530 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
16540 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
16550 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
16560 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
16570 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
16580 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
16590 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
165a0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
165b0 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
165c0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
165d0 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
165e0 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
165f0 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
16600 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
16610 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
16620 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
16630 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
16640 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
16650 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
16660 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
16670 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
16680 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
16690 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
166a0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
166b0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
166c0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
166d0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
166e0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
166f0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
16700 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
16710 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
16720 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
16730 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
16740 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
16750 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
16760 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
16770 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
16780 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
16790 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
167a0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
167b0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
167c0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
167d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
167e0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
167f0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
16800 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
16810 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
16820 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
16830 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
16840 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
16850 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
16860 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16870 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
16880 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
16890 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
168a0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
168b0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
168c0 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
168d0 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
168e0 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
168f0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
16900 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16910 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
16920 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
16930 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
16940 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
16950 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
16960 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
16970 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
16980 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16990 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20  LOOKASIDE       
169a0 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69  1001  /* void* i
169b0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
169c0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
169d0 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20  G_ENABLE_FKEY   
169e0 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69    1002  /* int i
169f0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
16a00 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
16a10 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31  NABLE_TRIGGER  1
16a20 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  003  /* int int*
16a30 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   */.../*.** CAPI
16a40 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
16a50 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
16a60 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
16a70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
16a80 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
16a90 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65  _codes() routine
16aa0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
16ab0 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74  bles the.** [ext
16ac0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
16ad0 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53  es] feature of S
16ae0 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65  QLite. ^The exte
16af0 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
16b00 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65  odes are disable
16b10 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
16b20 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70   historical comp
16b30 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e  atibility..*/.in
16b40 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
16b50 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
16b60 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
16b70 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
16b80 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
16b90 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e  rt Rowid.**.** ^
16ba0 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f  Each entry in mo
16bb0 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73  st SQLite tables
16bc0 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49   (except for [WI
16bd0 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
16be0 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e  les).** has a un
16bf0 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
16c00 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
16c10 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
16c20 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
16c30 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
16c40 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
16c50 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
16c60 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
16c70 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
16c80 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
16c90 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
16ca0 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
16cb0 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
16cc0 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
16cd0 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
16ce0 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
16cf0 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
16d00 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
16d10 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
16d20 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
16d30 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
16d40 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
16d50 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
16d60 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72  t_rowid(D) inter
16d70 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
16d80 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
16d90 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
16da0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
16db0 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64  RT] into a rowid
16dc0 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75   table or [virtu
16dd0 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20  al table].** on 
16de0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16df0 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72  ion D..** ^Inser
16e00 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
16e10 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
16e20 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e  re not recorded.
16e30 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  .** ^If no succe
16e40 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
16e50 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
16e60 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
16e70 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64  ccurred on the d
16e80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16e90 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73  on D, .** then s
16ea0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
16eb0 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75  rt_rowid(D) retu
16ec0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
16ed0 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
16ee0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
16ef0 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68   trigger or with
16f00 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  in a [virtual ta
16f10 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20  ble].** method, 
16f20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
16f30 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
16f40 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
16f50 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
16f60 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
16f70 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
16f80 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
16f90 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
16fa0 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
16fb0 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
16fc0 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73  able method ends
16fd0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
16fe0 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
16ff0 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
17000 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
17010 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
17020 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a  er or virtual.**
17030 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65   table method be
17040 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  gan.)^.**.** ^An
17050 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
17060 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
17070 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
17080 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
17090 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
170a0 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
170b0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
170c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
170d0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
170e0 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
170f0 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
17100 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
17110 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
17120 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
17130 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
17140 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
17150 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
17160 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
17170 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
17180 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
17190 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
171a0 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
171b0 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
171c0 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
171d0 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
171e0 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
171f0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
17200 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
17210 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
17220 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
17230 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
17240 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
17250 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
17260 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
17270 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
17280 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
17290 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
172a0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
172b0 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
172c0 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
172d0 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
172e0 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
172f0 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
17300 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
17310 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
17320 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
17330 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
17340 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
17350 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
17360 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
17370 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
17380 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
17390 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
173a0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
173b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
173c0 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
173d0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
173e0 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
173f0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
17400 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
17410 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
17420 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
17430 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
17440 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
17450 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
17460 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
17470 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
17480 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
17490 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
174a0 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
174b0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
174c0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
174d0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
174e0 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
174f0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
17500 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
17510 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
17520 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e  Modified.**.** ^
17530 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
17540 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
17550 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
17560 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a  d, inserted or.*
17570 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  * deleted by the
17580 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
17590 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
175a0 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
175b0 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f  E.** statement o
175c0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
175d0 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66  onnection specif
175e0 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20  ied by the only 
175f0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45  parameter..** ^E
17600 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
17610 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
17620 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
17630 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c  t modify the val
17640 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
17650 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  y this function.
17660 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61  .**.** ^Only cha
17670 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74  nges made direct
17680 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54  ly by the INSERT
17690 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
176a0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
176b0 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d  .** considered -
176c0 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   auxiliary chang
176d0 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52  es caused by [CR
176e0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
176f0 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66  riggers], .** [f
17700 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
17710 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d  ns] or [REPLACE]
17720 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
17730 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63  lution are not c
17740 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43  ounted..** .** C
17750 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
17760 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
17770 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e  epted by .** [IN
17780 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
17790 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72   | INSTEAD OF tr
177a0 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20  iggers] are not 
177b0 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61  counted. ^The va
177c0 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64  lue .** returned
177d0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
177e0 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c  ges() immediatel
177f0 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52  y after an INSER
17800 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a  T, UPDATE or .**
17810 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
17820 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20  t run on a view 
17830 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20  is always zero. 
17840 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
17850 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61  e to real .** ta
17860 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  bles are counted
17870 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61  ..**.** Things a
17880 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61  re more complica
17890 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74  ted if the sqlit
178a0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
178b0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63  ction is.** exec
178c0 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69  uted while a tri
178d0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20  gger program is 
178e0 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61  running. This ma
178f0 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a  y happen if the.
17900 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  ** program uses 
17910 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
17920 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72  QL function], or
17930 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63   if some other c
17940 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
17950 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69  ion invokes sqli
17960 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69  te3_changes() di
17970 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61  rectly. Essentia
17980 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e  lly:.** .** <ul>
17990 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66  .**   <li> ^(Bef
179a0 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74  ore entering a t
179b0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74  rigger program t
179c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
179d0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73  d by.**        s
179e0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
179f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76   function is sav
17a00 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72  ed. After the tr
17a10 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a  igger program .*
17a20 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e  *        has fin
17a30 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69  ished, the origi
17a40 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73  nal value is res
17a50 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20  tored.)^.** .** 
17a60 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20    <li> ^(Within 
17a70 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
17a80 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55  m each INSERT, U
17a90 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45  PDATE and DELETE
17aa0 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74   .**        stat
17ab0 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76  ement sets the v
17ac0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
17ad0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
17ae0 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70  () .**        up
17af0 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73  on completion as
17b00 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72   normal. Of cour
17b10 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77  se, this value w
17b20 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  ill not include 
17b30 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63  .**        any c
17b40 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64  hanges performed
17b50 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73   by sub-triggers
17b60 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33  , as the sqlite3
17b70 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
17b80 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c        value will
17b90 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65   be saved and re
17ba0 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63  stored after eac
17bb0 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61  h sub-trigger ha
17bc0 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c  s run.)^.** </ul
17bd0 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d  >.** .** ^This m
17be0 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65  eans that if the
17bf0 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66   changes() SQL f
17c00 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69  unction (or simi
17c10 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20  lar) is used.** 
17c20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53  by the first INS
17c30 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
17c40 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
17c50 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
17c60 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73  , it .** returns
17c70 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65   the value as se
17c80 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69  t when the calli
17c90 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67  ng statement beg
17ca0 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  an executing..**
17cb0 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20   ^If it is used 
17cc0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72  by the second or
17cd0 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68   subsequent such
17ce0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
17cf0 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20  n a trigger .** 
17d00 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c  program, the val
17d10 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c  ue returned refl
17d20 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20  ects the number 
17d30 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
17d40 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76   by the .** prev
17d50 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44  ious INSERT, UPD
17d60 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
17d70 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
17d80 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
17d90 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
17da0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
17db0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
17dc0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
17dd0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
17de0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
17df0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
17e00 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
17e10 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
17e20 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
17e30 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
17e40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17e50 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
17e60 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
17e70 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
17e80 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17e90 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
17ea0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
17eb0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
17ec0 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
17ed0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
17ee0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
17ef0 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
17f00 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
17f10 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
17f20 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74   returns the tot
17f30 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  al number of row
17f40 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69  s inserted, modi
17f50 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  fied or.** delet
17f60 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52  ed by all [INSER
17f70 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  T], [UPDATE] or 
17f80 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
17f90 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a  nts completed.**
17fa0 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62   since the datab
17fb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
17fc0 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75  as opened, inclu
17fd0 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75  ding those execu
17fe0 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ted as.** part o
17ff0 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  f trigger progra
18000 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61  ms. ^Executing a
18010 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
18020 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
18030 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63  * does not affec
18040 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
18050 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
18060 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e  total_changes().
18070 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  .** .** ^Changes
18080 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
18090 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
180a0 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75  tions] are inclu
180b0 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f  ded in the.** co
180c0 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d  unt, but those m
180d0 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52  ade as part of R
180e0 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
180f0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
18100 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65  .** not. ^Change
18110 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
18120 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
18130 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74   by INSTEAD OF t
18140 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20  riggers .** are 
18150 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
18160 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
18170 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
18180 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
18190 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
181a0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
181b0 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
181c0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
181d0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
181e0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
181f0 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
18200 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
18210 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
18220 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
18230 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
18240 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
18250 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
18260 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
18270 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
18280 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
18290 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
182a0 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
182b0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
182c0 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
182d0 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
182e0 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  Query.**.** ^Thi
182f0 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
18300 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
18310 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
18320 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
18330 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
18340 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
18350 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
18360 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
18370 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
18380 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
18390 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
183a0 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
183b0 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
183c0 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
183d0 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
183e0 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
183f0 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
18400 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61  .**.** ^It is sa
18410 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
18420 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
18430 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
18440 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
18450 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
18460 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
18470 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
18480 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
18490 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
184a0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
184b0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
184c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
184d0 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
184e0 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
184f0 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
18500 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
18510 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  s..**.** ^If an 
18520 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
18530 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
18540 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
18550 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
18560 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
18570 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
18580 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
18590 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
185a0 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
185b0 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
185c0 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
185d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  tion..**.** ^An 
185e0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
185f0 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
18600 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
18610 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
18620 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74  ..** ^If the int
18630 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
18640 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53  ration is an INS
18650 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
18660 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69  DELETE.** that i
18670 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
18680 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
18690 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
186a0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a  e transaction.**
186b0 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
186c0 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
186d0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
186e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
186f0 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65  (D) call is in e
18700 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20  ffect until all 
18710 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
18720 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
18730 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  nts on [database
18740 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63   connection] D c
18750 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e  omplete.  ^Any n
18760 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
18770 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
18780 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
18790 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
187a0 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
187b0 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
187c0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
187d0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
187e0 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
187f0 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
18800 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
18810 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
18820 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
18830 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74  .  ^New SQL stat
18840 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
18850 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
18860 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
18870 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
18880 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
18890 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
188a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
188b0 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20  errupt()..** ^A 
188c0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
188d0 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61  interrupt(D) tha
188e0 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68  t occurs when th
188f0 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69  ere are no runni
18900 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
18910 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20  ents is a no-op 
18920 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63  and has no effec
18930 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t on SQL stateme
18940 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
18950 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
18960 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
18970 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72  upt() call retur
18980 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ns..**.** If the
18990 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
189a0 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
189b0 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
189c0 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75  rupt()].** is ru
189d0 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
189e0 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
189f0 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69  y happen..*/.voi
18a00 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
18a10 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
18a20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18a30 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
18a40 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
18a50 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
18a60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
18a70 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
18a80 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
18a90 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
18aa0 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
18ab0 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
18ac0 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
18ad0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
18ae0 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
18af0 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
18b00 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
18b10 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
18b20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
18b30 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
18b40 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
18b50 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68  s return 1 if th
18b60 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
18b70 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
18b80 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
18b90 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74  tatement.  ^A st
18ba0 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
18bb0 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
18bc0 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
18bd0 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
18be0 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
18bf0 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a   a prefix of a.*
18c00 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52  * well-formed CR
18c10 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
18c20 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f  tement.  ^Semico
18c30 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
18c40 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
18c50 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
18c60 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
18c70 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
18c80 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
18c90 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
18ca0 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
18cb0 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
18cc0 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
18cd0 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
18ce0 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
18cf0 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
18d00 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
18d10 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a  .  ^Whitespace.*
18d20 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74  * and comments t
18d30 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66  hat follow the f
18d40 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  inal semicolon a
18d50 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  re ignored..**.*
18d60 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
18d70 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68  s return 0 if th
18d80 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69  e statement is i
18d90 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20  ncomplete.  ^If 
18da0 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
18db0 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
18dc0 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
18dd0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
18de0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
18df0 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
18e00 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
18e10 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
18e20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
18e30 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
18e40 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ct SQL..**.** ^(
18e50 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
18e60 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
18e70 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
18e80 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
18e90 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
18ea0 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
18eb0 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
18ec0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
18ed0 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
18ee0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
18ef0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
18f00 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
18f10 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
18f20 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
18f30 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
18f40 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
18f50 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
18f60 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
18f70 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
18f80 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
18f90 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
18fa0 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  mplete.)^.**.** 
18fb0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
18fc0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
18fd0 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
18fe0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
18ff0 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
19000 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
19010 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
19020 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
19030 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
19040 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
19050 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
19060 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73   order..*/.int s
19070 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
19080 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
19090 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
190a0 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
190b0 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
190c0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
190d0 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
190e0 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
190f0 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20  _BUSY Errors.** 
19100 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d  KEYWORDS: {busy-
19110 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
19120 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d  } {busy handler}
19130 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
19140 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
19150 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20  (D,X,P) routine 
19160 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
19170 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68  function X.** th
19180 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
19190 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ked with argumen
191a0 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  t P whenever.** 
191b0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
191c0 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64  de to access a d
191d0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73  atabase table as
191e0 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
191f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
19200 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e  ction] D when an
19210 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
19220 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74  or process has t
19230 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e  he table locked.
19240 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
19250 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69  busy_handler() i
19260 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
19270 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a   to implement.**
19280 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
19290 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50  imeout()] and [P
192a0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
192b0 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ut]..**.** ^If t
192c0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
192d0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
192e0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
192f0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
19300 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
19310 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
19320 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
19330 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
19340 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
19350 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
19360 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
19370 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
19380 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
19390 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
193a0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
193b0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
193c0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
193d0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
193e0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
193f0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
19400 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
19410 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
19420 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
19430 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
19440 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
19450 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
19460 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
19470 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
19480 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74  previously for t
19490 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20  he same locking 
194a0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
194b0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
194c0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
194d0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
194e0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
194f0 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
19500 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
19510 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20  SQLITE_BUSY] is 
19520 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74  returned.** to t
19530 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a  he application..
19540 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
19550 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
19560 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
19570 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
19580 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
19590 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
195a0 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
195b0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
195c0 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
195d0 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
195e0 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
195f0 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
19600 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
19610 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
19620 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
19630 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
19640 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
19650 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
19660 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
19670 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
19680 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
19690 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
196a0 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  SY].** to the ap
196b0 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61  plication instea
196c0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
196d0 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  e .** busy handl
196e0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
196f0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
19700 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
19710 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
19720 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
19730 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
19740 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
19750 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
19760 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
19770 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
19780 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
19790 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
197a0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
197b0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
197c0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
197d0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
197e0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
197f0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
19800 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
19810 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
19820 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
19830 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
19840 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
19850 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
19860 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
19870 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
19880 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
19890 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
198a0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
198b0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
198c0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
198d0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
198e0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
198f0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
19900 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
19910 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
19920 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
19930 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
19940 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
19950 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
19960 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
19970 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
19980 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
19990 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
199a0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
199b0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
199c0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
199d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
199e0 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
199f0 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
19a00 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
19a10 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
19a20 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
19a30 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
19a40 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
19a50 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c  ut()].** or eval
19a60 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62  uating [PRAGMA b
19a70 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77  usy_timeout=N] w
19a80 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a  ill change the.*
19a90 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61  * busy handler a
19aa0 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e  nd thus clear an
19ab0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  y previously set
19ac0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
19ad0 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
19ae0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
19af0 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
19b00 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
19b10 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
19b20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
19b30 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
19b40 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74   handler.  In ot
19b50 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68  her words,.** th
19b60 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
19b70 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  s not reentrant.
19b80 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
19b90 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
19ba0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
19bb0 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
19bc0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
19bd0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
19be0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19bf0 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
19c00 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
19c10 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
19c20 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
19c30 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
19c40 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
19c50 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
19c60 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
19c70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
19c80 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
19c90 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
19ca0 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
19cb0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
19cc0 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
19cd0 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
19ce0 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
19cf0 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
19d00 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
19d10 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
19d20 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
19d30 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
19d40 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
19d50 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
19d60 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
19d70 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
19d80 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
19d90 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
19da0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
19db0 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
19dc0 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
19dd0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
19de0 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
19df0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
19e00 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  BUSY]..**.** ^Ca
19e10 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
19e20 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
19e30 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
19e40 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
19e50 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
19e60 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
19e70 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
19e80 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
19e90 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
19ea0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
19eb0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
19ec0 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20  nection] at any 
19ed0 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
19ee0 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
19ef0 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
19f00 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
19f10 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
19f20 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
19f30 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
19f40 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
19f50 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
19f60 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
19f70 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
19f80 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
19f90 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71  meout].*/.int sq
19fa0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
19fb0 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
19fc0 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
19fd0 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
19fe0 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
19ff0 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
1a000 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1a010 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1a020 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1a030 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1a040 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1a050 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1a060 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1a070 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1a080 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1a090 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1a0a0 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1a0b0 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1a0c0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1a0d0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1a0e0 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1a0f0 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1a100 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1a110 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1a120 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1a130 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1a140 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1a150 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1a160 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1a170 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1a180 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1a190 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1a1a0 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1a1b0 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1a1c0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1a1d0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1a1e0 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1a1f0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1a200 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1a210 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1a220 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1a230 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1a240 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1a250 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1a260 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1a270 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1a280 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1a290 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1a2a0 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1a2b0 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1a2c0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1a2d0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1a2e0 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1a2f0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1a300 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1a310 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1a320 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1a330 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1a340 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1a350 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1a360 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1a370 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1a380 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1a390 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1a3a0 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1a3b0 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1a3c0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1a3d0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1a3e0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1a3f0 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1a400 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1a410 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1a420 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1a430 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1a440 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1a450 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1a460 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1a470 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1a480 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1a490 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1a4a0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1a4b0 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1a4c0 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1a4d0 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1a4e0 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1a4f0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1a500 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1a510 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1a520 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1a530 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1a540 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1a550 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1a560 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1a570 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1a580 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1a590 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1a5a0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1a5b0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1a5c0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1a5d0 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1a5e0 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1a5f0 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1a600 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1a610 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1a620 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1a630 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1a640 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1a650 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1a660 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1a670 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1a680 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1a690 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1a6a0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1a6b0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1a6c0 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1a6d0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a6e0 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1a6f0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a700 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1a710 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a720 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1a730 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1a740 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1a750 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1a760 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1a770 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1a780 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a790 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1a7a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1a7b0 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1a7c0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1a7d0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1a7e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1a7f0 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1a800 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1a810 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1a820 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1a830 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1a840 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1a850 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1a860 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1a870 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1a880 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1a890 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1a8a0 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1a8b0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1a8c0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1a8d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1a8e0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1a8f0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1a900 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1a910 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1a920 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1a930 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1a940 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1a950 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1a960 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1a970 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1a980 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1a990 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1a9a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1a9b0 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1a9c0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1a9d0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1a9e0 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1a9f0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1aa00 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1aa10 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1aa20 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1aa30 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1aa40 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1aa50 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1aa60 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1aa70 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1aa80 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1aa90 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1aaa0 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1aab0 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1aac0 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1aad0 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1aae0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1aaf0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1ab00 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1ab10 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1ab20 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1ab30 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1ab40 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1ab50 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1ab60 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1ab70 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1ab80 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1ab90 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1aba0 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1abb0 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1abc0 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1abd0 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1abe0 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1abf0 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1ac00 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1ac10 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1ac20 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1ac30 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  g()]..*/.int sql
1ac40 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1ac50 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1ac60 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1ac70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1ac80 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1ac90 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1aca0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1acb0 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1acc0 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1acd0 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1ace0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1acf0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1ad00 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1ad10 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1ad20 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1ad30 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1ad40 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1ad50 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1ad60 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1ad70 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1ad80 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1ad90 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1ada0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1adb0 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
1adc0 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
1add0 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
1ade0 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
1adf0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1ae00 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1ae10 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
1ae20 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
1ae30 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
1ae40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
1ae50 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1ae60 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  library..**.** ^
1ae70 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
1ae80 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
1ae90 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
1aea0 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
1aeb0 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
1aec0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
1aed0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
1aee0 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
1aef0 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
1af00 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
1af10 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
1af20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
1af30 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
1af40 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
1af50 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
1af60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
1af70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1af80 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
1af90 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
1afa0 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
1afb0 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
1afc0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
1afd0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  The sqlite3_snpr
1afe0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1aff0 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
1b000 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
1b010 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
1b020 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
1b030 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
1b040 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
1b050 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
1b060 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1b070 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
1b080 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
1b090 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1b0a0 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
1b0b0 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
1b0c0 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
1b0d0 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
1b0e0 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
1b0f0 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61  ().)^  This is a
1b100 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
1b110 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
1b120 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
1b130 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
1b140 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
1b150 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f  atibility.  ^(No
1b160 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
1b170 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1b180 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
1b190 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
1b1a0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1b1b0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
1b1c0 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
1b1d0 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
1b1e0 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57  the buffer.)^  W
1b1f0 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
1b200 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
1b210 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
1b220 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
1b230 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
1b240 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
1b250 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
1b260 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1b270 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1b280 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
1b290 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
1b2a0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
1b2b0 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74  ** ^As long as t
1b2c0 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
1b2d0 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
1b2e0 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
1b2f0 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
1b300 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
1b310 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
1b320 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
1b330 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20    ^The first.** 
1b340 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
1b350 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
1b360 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
1b370 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
1b380 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
1b390 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
1b3a0 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
1b3b0 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
1b3c0 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
1b3d0 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
1b3e0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
1b3f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1b400 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1b410 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20  ne is a varargs 
1b420 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74  version of sqlit
1b430 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a  e3_snprintf()..*
1b440 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1b450 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  nes all implemen
1b460 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  t some additiona
1b470 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20  l formatting.** 
1b480 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  options that are
1b490 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73   useful for cons
1b4a0 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61  tructing SQL sta
1b4b0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20  tements..** All 
1b4c0 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69  of the usual pri
1b4d0 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67  ntf() formatting
1b4e0 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20   options apply. 
1b4f0 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68   In addition, th
1b500 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25  ere.** is are "%
1b510 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25  q", "%Q", and "%
1b520 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  z" options..**.*
1b530 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f  * ^(The %q optio
1b540 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
1b550 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
1b560 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72  itutes a nul-ter
1b570 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1b580 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
1b590 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
1b5a0 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
1b5b0 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
1b5c0 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
1b5d0 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
1b5e0 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
1b5f0 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f  iteral.)^  By do
1b600 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
1b610 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
1b620 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
1b630 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
1b640 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
1b650 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
1b660 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
1b670 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
1b680 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
1b690 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
1b6a0 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
1b6b0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1b6c0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1b6d0 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
1b6e0 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
1b6f0 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
1b700 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1b710 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
1b720 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
1b730 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
1b740 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1b750 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1b760 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1b770 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1b780 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1b790 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
1b7a0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1b7b0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1b7c0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1b7d0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1b7e0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1b7f0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1b800 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
1b810 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
1b820 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
1b830 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
1b840 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
1b850 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
1b860 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is 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 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1b8a0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1b8b0 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
1b8c0 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
1b8d0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1b8e0 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
1b8f0 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
1b900 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
1b910 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
1b920 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
1b930 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
1b940 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
1b950 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1b960 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1b970 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1b980 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1b990 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1b9a0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1b9b0 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
1b9c0 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
1b9d0 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
1b9e0 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
1b9f0 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
1ba00 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
1ba10 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
1ba20 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
1ba30 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1ba40 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  l..**.** ^(The %
1ba50 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
1ba60 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
1ba70 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
1ba80 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
1ba90 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
1baa0 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
1bab0 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
1bac0 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
1bad0 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
1bae0 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
1baf0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
1bb00 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
1bb10 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
1bb20 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
1bb30 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c   quotes).)^  So,
1bb40 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
1bb50 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
1bb60 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1bb70 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1bb80 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1bb90 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1bba0 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1bbb0 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
1bbc0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1bbd0 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1bbe0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1bbf0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1bc00 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1bc10 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
1bc20 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
1bc30 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
1bc40 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
1bc50 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
1bc60 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
1bc70 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
1bc80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1bc90 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a  .**.** ^(The "%z
1bca0 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1bcb0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22  ion works like "
1bcc0 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65  %s" but with the
1bcd0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
1bce0 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
1bcf0 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
1bd00 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
1bd10 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
1bd20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1bd30 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
1bd40 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29  e input string.)
1bd50 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ^.*/.char *sqlit
1bd60 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
1bd70 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
1bd80 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
1bd90 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1bda0 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
1bdb0 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
1bdc0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1bdd0 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63  t char*, ...);.c
1bde0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e  har *sqlite3_vsn
1bdf0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1be00 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  ,const char*, va
1be10 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _list);../*.** C
1be20 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1be30 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
1be40 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
1be50 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
1be60 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
1be70 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
1be80 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
1be90 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
1bea0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
1beb0 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
1bec0 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
1bed0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
1bee0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
1bef0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
1bf00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1bf10 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
1bf20 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
1bf30 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1bf40 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
1bf50 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
1bf60 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1bf70 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
1bf80 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1bf90 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
1bfa0 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
1bfb0 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
1bfc0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1bfd0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1bfe0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
1bff0 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
1c000 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
1c010 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
1c020 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
1c030 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1c040 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
1c050 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
1c060 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
1c070 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
1c080 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
1c090 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
1c0a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1c0b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1c0c0 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f  3_malloc64(N) ro
1c0d0 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74  utine works just
1c0e0 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33   like.** sqlite3
1c0f0 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70  _malloc(N) excep
1c100 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75  t that N is an u
1c110 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69  nsigned 64-bit i
1c120 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1c130 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32  * of a signed 32
1c140 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  -bit integer..**
1c150 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
1c160 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
1c170 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
1c180 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
1c190 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
1c1a0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1c1b0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
1c1c0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
1c1d0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
1c1e0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
1c1f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
1c200 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
1c210 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
1c220 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
1c230 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
1c240 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
1c250 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
1c260 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
1c270 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
1c280 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
1c290 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
1c2a0 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
1c2b0 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
1c2c0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
1c2d0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
1c2e0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
1c2f0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1c300 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
1c310 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
1c320 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
1c330 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
1c340 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
1c350 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
1c360 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
1c370 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
1c380 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1c390 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
1c3a0 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
1c3b0 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
1c3c0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c3d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1c3e0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  lloc()..**.** ^T
1c3f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1c400 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  oc(X,N) interfac
1c410 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1c420 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1c430 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c440 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61  n X to be at lea
1c450 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  st N bytes..** ^
1c460 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74  If the X paramet
1c470 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1c480 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73  alloc(X,N).** is
1c490 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1c4a0 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
1c4b0 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
1c4c0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
1c4d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a  ite3_malloc(N)..
1c4e0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72  ** ^If the N par
1c4f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1c500 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1c510 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
1c520 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
1c530 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
1c540 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
1c550 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1c560 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73  3_free(X)..** ^s
1c570 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1c580 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ,N) returns a po
1c590 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1c5a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1c5b0 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1c5c0 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1c5d0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
1c5e0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76  ent memory is av
1c5f0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1c600 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1c610 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1c620 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1c630 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1c640 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1c650 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1c660 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1c670 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1c680 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1c690 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1c6a0 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1c6b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1c6c0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1c6d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1c6e0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
1c6f0 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c  d N is positive,
1c700 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69   then the.** pri
1c710 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1c720 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
1c730 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1c740 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e  ealloc64(X,N) in
1c750 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74  terfaces works t
1c760 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
1c770 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1c780 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1c790 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73   is a 64-bit uns
1c7a0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e  igned integer in
1c7b0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32  stead.** of a 32
1c7c0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1c7d0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58  ger..**.** ^If X
1c7e0 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   is a memory all
1c7f0 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73  ocation previous
1c800 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
1c810 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c820 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ),.** sqlite3_ma
1c830 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65  lloc64(), sqlite
1c840 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20  3_realloc(), or 
1c850 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1c860 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  4(), then.** sql
1c870 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1c880 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
1c890 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c  f that memory al
1c8a0 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65  location in byte
1c8b0 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  s..** ^The value
1c8c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1c8d0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69  ite3_msize(X) mi
1c8e0 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68  ght be larger th
1c8f0 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  an the number.**
1c900 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73   of bytes reques
1c910 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61  ted when X was a
1c920 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58  llocated.  ^If X
1c930 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1c940 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  er then.** sqlit
1c950 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1c960 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20  rns zero.  If X 
1c970 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68  points to someth
1c980 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a  ing that is not.
1c990 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  ** the beginning
1c9a0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
1c9b0 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20  ation, or if it 
1c9c0 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d  points to a form
1c9d0 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65  erly.** valid me
1c9e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1c9f0 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65  that has now bee
1ca00 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68  n freed, then th
1ca10 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
1ca20 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1ca30 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  ) is undefined a
1ca40 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d  nd possibly harm
1ca50 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ful..**.** ^The 
1ca60 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
1ca70 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1ca80 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61  c(), sqlite3_rea
1ca90 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
1caa0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61  e3_malloc64(), a
1cab0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
1cac0 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77  oc64().** is alw
1cad0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
1cae0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
1caf0 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
1cb00 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
1cb10 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
1cb20 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
1cb30 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
1cb40 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
1cb50 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
1cb60 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
1cb70 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
1cb80 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
1cb90 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
1cba0 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
1cbb0 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
1cbc0 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
1cbd0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
1cbe0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
1cbf0 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
1cc00 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
1cc10 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
1cc20 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
1cc30 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
1cc40 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
1cc50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
1cc60 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
1cc70 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
1cc80 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1cc90 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77  7.10, the Window
1cca0 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
1ccb0 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  ayer called.** t
1ccc0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
1ccd0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
1cce0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
1ccf0 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
1cd00 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
1cd10 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
1cd20 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
1cd30 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
1cd40 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
1cd50 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
1cd60 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
1cd70 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
1cd80 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
1cd90 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72  ation errors wer
1cda0 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
1cdb0 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70  ** they were rep
1cdc0 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
1cdd0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
1cde0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
1cdf0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
1ce00 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
1ce10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1ce20 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
1ce30 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1ce40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1ce50 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
1ce60 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
1ce70 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
1ce80 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1ce90 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
1cea0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1ceb0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
1cec0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ced0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
1cee0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
1cef0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
1cf00 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
1cf10 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
1cf20 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
1cf30 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
1cf40 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
1cf50 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
1cf60 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1cf70 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
1cf80 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
1cf90 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1cfa0 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
1cfb0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
1cfc0 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69  loc64(sqlite3_ui
1cfd0 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  nt64);.void *sql
1cfe0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
1cff0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  d*, int);.void *
1d000 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1d010 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  4(void*, sqlite3
1d020 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  _uint64);.void s
1d030 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
1d040 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74  *);.sqlite3_uint
1d050 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  64 sqlite3_msize
1d060 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1d070 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1d080 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1d090 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1d0a0 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1d0b0 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1d0c0 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1d0d0 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1d0e0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1d0f0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1d100 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1d110 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1d120 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1d130 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1d140 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1d150 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1d160 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1d170 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1d180 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1d190 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1d1a0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1d1b0 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1d1c0 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1d1d0 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1d1e0 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1d1f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1d200 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1d210 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1d220 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1d230 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1d240 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1d250 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1d260 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1d270 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1d280 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1d290 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1d2a0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1d2b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1d2c0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1d2d0 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1d2e0 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1d2f0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1d300 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1d310 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1d320 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1d330 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1d340 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1d350 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1d360 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1d370 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1d380 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1d390 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1d3a0 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1d3b0 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1d3c0 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1d3d0 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1d3e0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1d3f0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1d400 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1d410 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1d420 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1d430 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1d440 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1d450 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1d460 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1d470 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1d480 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1d490 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1d4a0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
1d4b0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1d4c0 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
1d4d0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1d4e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1d4f0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
1d500 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
1d510 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
1d520 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
1d530 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
1d540 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
1d550 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
1d560 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
1d570 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
1d580 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
1d590 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
1d5a0 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
1d5b0 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
1d5c0 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
1d5d0 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
1d5e0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
1d5f0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
1d600 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
1d610 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
1d620 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
1d630 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
1d640 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
1d650 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
1d660 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
1d670 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
1d680 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
1d690 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
1d6a0 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
1d6b0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
1d6c0 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
1d6d0 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
1d6e0 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
1d6f0 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  er P..** ^The P 
1d700 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65  parameter can be
1d710 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1d720 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20  .**.** ^If this 
1d730 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20  routine has not 
1d740 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  been previously 
1d750 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65  called or if the
1d760 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c   previous.** cal
1d770 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61  l had N less tha
1d780 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20  n one or a NULL 
1d790 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74  pointer for P, t
1d7a0 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a  hen the PRNG is.
1d7b0 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  ** seeded using 
1d7c0 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
1d7d0 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61  ned from the xRa
1d7e0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1d7f0 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  of.** the defaul
1d800 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1d810 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74  object..** ^If t
1d820 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
1d830 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1d840 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f   had an N of 1 o
1d850 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20  r more and a.** 
1d860 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20  non-NULL P then 
1d870 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
1d880 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
1d890 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
1d8a0 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
1d8b0 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
1d8c0 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
1d8d0 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
1d8e0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
1d8f0 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
1d900 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
1d910 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1d920 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
1d930 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
1d940 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  cks.**.** ^This 
1d950 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
1d960 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  s an authorizer 
1d970 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
1d980 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1d990 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d9a0 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
1d9b0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1d9c0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
1d9d0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d9e0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
1d9f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
1da00 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
1da10 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1da20 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1da30 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
1da40 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1da50 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
1da60 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
1da70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1da80 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
1da90 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
1daa0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
1dab0 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
1dac0 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
1dad0 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
1dae0 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
1daf0 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
1db00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1db10 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
1db20 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
1db30 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
1db40 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
1db50 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
1db60 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
1db70 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
1db80 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
1db90 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1dba0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
1dbb0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
1dbc0 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
1dbd0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1dbe0 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
1dbf0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
1dc00 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
1dc10 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
1dc20 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
1dc30 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
1dc40 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
1dc50 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
1dc60 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1dc70 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
1dc80 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
1dc90 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
1dca0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
1dcb0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
1dcc0 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
1dcd0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1dce0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1dcf0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1dd00 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
1dd10 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1dd20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1dd30 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
1dd40 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1dd50 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
1dd60 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
1dd70 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
1dd80 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
1dd90 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
1dda0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1ddb0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
1ddc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1ddd0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1dde0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1ddf0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
1de00 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
1de10 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1de20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
1de30 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
1de40 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
1de50 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
1de60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1de70 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1de80 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
1de90 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
1dea0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
1deb0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
1dec0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
1ded0 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
1dee0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
1def0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1df00 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1df10 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
1df20 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
1df30 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
1df40 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
1df50 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1df60 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
1df70 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
1df80 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
1df90 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
1dfa0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1dfb0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
1dfc0 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
1dfd0 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
1dfe0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
1dff0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
1e000 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
1e010 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1e020 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
1e030 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1e040 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
1e050 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
1e060 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
1e070 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
1e080 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
1e090 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
1e0a0 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
1e0b0 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
1e0c0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
1e0d0 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
1e0e0 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
1e0f0 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
1e100 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
1e110 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
1e120 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
1e130 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
1e140 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
1e150 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
1e160 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
1e170 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
1e180 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1e190 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
1e1a0 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
1e1b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1e1c0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1e1d0 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
1e1e0 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
1e1f0 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
1e200 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
1e210 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
1e220 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
1e230 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
1e240 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
1e250 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
1e260 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
1e270 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1e280 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
1e290 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
1e2a0 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
1e2b0 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
1e2c0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
1e2d0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
1e2e0 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
1e2f0 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
1e300 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
1e310 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
1e320 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
1e330 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
1e340 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
1e350 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
1e360 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
1e370 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
1e380 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
1e390 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
1e3a0 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
1e3b0 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
1e3c0 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
1e3d0 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
1e3e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1e3f0 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
1e400 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
1e410 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
1e420 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
1e430 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
1e440 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
1e450 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
1e460 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
1e470 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
1e480 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
1e490 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1e4a0 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
1e4b0 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
1e4c0 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
1e4d0 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
1e4e0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
1e4f0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1e500 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
1e510 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
1e520 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
1e530 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
1e540 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
1e550 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
1e560 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1e570 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
1e580 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
1e590 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
1e5a0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1e5b0 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
1e5c0 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
1e5d0 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
1e5e0 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
1e5f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
1e600 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
1e610 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
1e620 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
1e630 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
1e640 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
1e650 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
1e660 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
1e670 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
1e680 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
1e690 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
1e6a0 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
1e6b0 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
1e6c0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
1e6d0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
1e6e0 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1e6f0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1e700 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1e710 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1e720 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1e730 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1e740 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
1e750 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e760 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
1e770 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e780 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1e790 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
1e7a0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
1e7b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e7c0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
1e7d0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
1e7e0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
1e7f0 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
1e800 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e810 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
1e820 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
1e830 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
1e840 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
1e850 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
1e860 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1e870 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
1e880 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
1e890 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
1e8a0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
1e8b0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
1e8c0 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
1e8d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1e8e0 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
1e8f0 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
1e900 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
1e910 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
1e920 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e930 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1e940 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
1e950 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e960 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1e970 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
1e980 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
1e990 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
1e9a0 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
1e9b0 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
1e9c0 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
1e9d0 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
1e9e0 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
1e9f0 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
1ea00 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
1ea10 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
1ea20 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
1ea30 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
1ea40 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
1ea50 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
1ea60 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1ea70 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
1ea80 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
1ea90 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1eaa0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1eab0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1eac0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
1ead0 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
1eae0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1eaf0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
1eb00 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
1eb10 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1eb20 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1eb30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1eb40 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
1eb50 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
1eb60 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
1eb70 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
1eb80 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
1eb90 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
1eba0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
1ebb0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
1ebc0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
1ebd0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
1ebe0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1ebf0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1ec00 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
1ec10 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
1ec20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1ec30 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
1ec40 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
1ec50 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
1ec60 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c   [conflict resol
1ec70 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72  ution mode].** r
1ec80 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65  eturned from the
1ec90 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
1eca0 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
1ecb0 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
1ecc0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
1ecd0 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
1ece0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1ecf0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
1ed00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ed10 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
1ed20 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
1ed30 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
1ed40 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
1ed50 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1ed60 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
1ed70 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
1ed80 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1ed90 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
1eda0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
1edb0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
1edc0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
1edd0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
1ede0 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
1edf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
1ee00 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
1ee10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1ee20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1ee30 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
1ee40 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
1ee50 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
1ee60 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
1ee70 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
1ee80 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
1ee90 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
1eea0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1eeb0 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
1eec0 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
1eed0 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
1eee0 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
1eef0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
1ef00 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
1ef10 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
1ef20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
1ef30 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1ef40 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
1ef50 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1ef60 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
1ef70 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
1ef80 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
1ef90 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
1efa0 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
1efb0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1efc0 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
1efd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1efe0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1eff0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1f000 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1f010 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
1f020 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
1f030 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
1f040 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
1f050 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1f060 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
1f070 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
1f080 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
1f090 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
1f0a0 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
1f0b0 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
1f0c0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
1f0d0 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
1f0e0 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
1f0f0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
1f100 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
1f110 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
1f120 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f130 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f140 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
1f150 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
1f160 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
1f170 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
1f180 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
1f190 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1f1a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1f1b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f1c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
1f1d0 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
1f1e0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f1f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f200 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f210 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1f220 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
1f230 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1f240 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f250 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f260 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1f270 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
1f280 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f290 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f2a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f2b0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
1f2c0 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
1f2d0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1f2e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f2f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f300 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
1f310 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
1f320 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1f330 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f350 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
1f360 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
1f370 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1f380 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1f3a0 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
1f3b0 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
1f3c0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1f3d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f3e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1f3f0 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
1f400 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
1f410 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f420 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f430 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f440 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
1f450 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
1f460 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1f470 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f480 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f490 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1f4a0 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
1f4b0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f4c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f4d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f4e0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
1f4f0 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
1f500 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1f510 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f520 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1f530 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
1f540 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1f550 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1f560 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f570 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1f580 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
1f590 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1f5a0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1f5b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f5c0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1f5d0 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
1f5e0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1f5f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f600 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f610 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
1f620 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
1f630 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1f640 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1f650 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f660 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
1f670 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
1f680 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1f690 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f6a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f6b0 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
1f6c0 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
1f6d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f6e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f6f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f700 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
1f710 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
1f720 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
1f730 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
1f740 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f750 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
1f760 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
1f770 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f780 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1f790 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f7a0 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
1f7b0 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
1f7c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
1f7d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f7e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f7f0 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
1f800 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
1f810 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
1f820 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f830 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f840 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
1f850 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
1f860 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
1f870 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
1f880 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1f890 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
1f8a0 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
1f8b0 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
1f8c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f8d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1f8e0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1f8f0 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
1f900 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
1f910 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f920 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
1f930 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
1f940 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
1f950 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
1f960 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f970 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
1f980 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
1f990 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
1f9a0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f9b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f9c0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
1f9d0 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
1f9e0 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
1f9f0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1fa00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1fa10 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1fa20 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
1fa30 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
1fa40 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1fa50 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1fa60 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
1fa70 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
1fa80 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1fa90 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1faa0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1fab0 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
1fac0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
1fad0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1fae0 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
1faf0 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
1fb00 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
1fb10 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
1fb20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1fb30 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
1fb40 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
1fb50 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
1fb60 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
1fb70 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
1fb80 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
1fb90 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20  ITE_RECURSIVE   
1fba0 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a           33   /*
1fbb0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1fbc0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1fbd0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1fbe0 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
1fbf0 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
1fc00 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
1fc10 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
1fc20 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1fc30 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
1fc40 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
1fc50 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
1fc60 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
1fc70 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
1fc80 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1fc90 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1fca0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1fcb0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1fcc0 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
1fcd0 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
1fce0 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
1fcf0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
1fd00 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
1fd10 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
1fd20 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
1fd30 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1fd40 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
1fd50 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
1fd60 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1fd70 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
1fd80 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
1fd90 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
1fda0 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
1fdb0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1fdc0 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
1fdd0 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
1fde0 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
1fdf0 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
1fe00 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
1fe10 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
1fe20 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
1fe30 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
1fe40 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
1fe50 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
1fe60 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  * The [SQLITE_TR
1fe70 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
1fe80 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
1fe90 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
1fea0 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20  to limit.** the 
1feb0 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64  length of [bound
1fec0 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61   parameter] expa
1fed0 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74  nsion in the out
1fee0 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74  put of sqlite3_t
1fef0 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  race()..**.** ^T
1ff00 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1ff10 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1ff20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
1ff30 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
1ff40 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
1ff50 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
1ff60 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
1ff70 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
1ff80 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
1ff90 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
1ffa0 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
1ffb0 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
1ffc0 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
1ffd0 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
1ffe0 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
1fff0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
20000 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
20010 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
20020 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
20030 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
20040 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
20050 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
20060 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
20070 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
20080 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
20090 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
200a0 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
200b0 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
200c0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
200d0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
200e0 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
200f0 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
20100 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
20110 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
20120 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
20130 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
20140 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
20150 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
20160 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
20170 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
20180 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
20190 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
201a0 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
201b0 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
201c0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
201d0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
201e0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
201f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
20200 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
20210 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
20220 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
20230 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
20240 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
20250 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
20260 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
20270 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
20280 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
20290 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
202a0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
202b0 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
202c0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
202d0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
202e0 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
202f0 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
20300 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
20310 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
20320 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
20330 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
20340 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
20350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20360 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
20370 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
20380 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
20390 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
203a0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
203b0 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
203c0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
203d0 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
203e0 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
203f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
20400 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
20410 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
20420 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
20430 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e  he approximate n
20440 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
20450 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
20460 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
20470 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
20480 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
20490 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
204a0 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
204b0 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65   X.  ^If N is le
204c0 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e  ss than one then
204d0 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a   the progress.**
204e0 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61   handler is disa
204f0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  bled..**.** ^Onl
20500 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
20510 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
20520 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
20530 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
20540 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20550 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
20560 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
20570 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
20580 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
20590 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
205a0 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
205b0 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
205c0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
205d0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
205e0 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
205f0 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
20600 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
20610 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
20620 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
20630 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
20640 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
20650 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
20660 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
20670 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
20680 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
20690 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
206a0 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
206b0 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
206c0 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
206d0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
206e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
206f0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
20700 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
20710 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
20720 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
20730 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
20740 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
20750 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
20760 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20770 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
20780 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
20790 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
207a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
207b0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
207c0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
207d0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
207e0 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ..**.*/.void sql
207f0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
20800 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
20810 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
20820 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
20830 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
20840 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
20850 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
20860 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
20870 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
20880 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
20890 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62  e as specified b
208a0 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61  y the .** filena
208b0 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68  me argument. ^Th
208c0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
208d0 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
208e0 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a  ed as UTF-8 for.
208f0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
20900 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
20910 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55  en_v2() and as U
20920 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
20930 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65  ive byte.** orde
20940 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  r for sqlite3_op
20950 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74  en16(). ^(A [dat
20960 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20970 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
20980 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
20990 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
209a0 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
209b0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
209c0 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
209d0 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
209e0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
209f0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
20a00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
20a10 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
20a20 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
20a30 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
20a40 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
20a50 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
20a60 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e  ].** object.)^ ^
20a70 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  (If the database
20a80 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f   is opened (and/
20a90 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63  or created) succ
20aa0 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a  essfully, then.*
20ab0 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  * [SQLITE_OK] is
20ac0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
20ad0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
20ae0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
20af0 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71  d.)^ ^The.** [sq
20b00 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
20b10 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
20b20 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
20b30 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
20b40 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
20b50 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
20b60 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
20b70 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67   error following
20b80 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e   a failure of an
20b90 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  y.** of the sqli
20ba0 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69  te3_open() routi
20bb0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nes..**.** ^The 
20bc0 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
20bd0 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66   will be UTF-8 f
20be0 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65  or databases cre
20bf0 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71  ated using.** sq
20c00 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
20c10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20c20 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74  ).  ^The default
20c30 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61   encoding for da
20c40 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74  tabases.** creat
20c50 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
20c60 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62  _open16() will b
20c70 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  e UTF-16 in the 
20c80 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
20c90 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  r..**.** Whether
20ca0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
20cb0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
20cc0 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
20cd0 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
20ce0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
20cf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20d00 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
20d10 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
20d20 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
20d30 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
20d40 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
20d50 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
20d60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
20d70 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
20d80 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
20d90 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
20da0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
20db0 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
20dc0 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
20dd0 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
20de0 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
20df0 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
20e00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
20e10 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
20e20 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
20e30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20e40 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
20e50 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
20e60 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
20e70 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
20e80 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
20e90 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
20ea0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
20eb0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
20ec0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
20ed0 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
20ee0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
20ef0 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
20f00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
20f10 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
20f20 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
20f30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
20f40 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
20f50 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
20f60 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
20f70 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
20f80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
20f90 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
20fa0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
20fb0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
20fc0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
20fd0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
20fe0 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
20ff0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
21000 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
21010 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
21020 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
21030 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
21040 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
21050 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
21060 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
21070 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
21080 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
21090 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
210a0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
210b0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
210c0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
210d0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
210e0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
210f0 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
21100 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
21110 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
21120 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
21130 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
21140 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
21150 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
21160 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
21170 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
21180 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
21190 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
211a0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
211b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
211c0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
211d0 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
211e0 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
211f0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
21200 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
21210 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
21220 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
21230 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
21240 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
21250 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
21260 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
21270 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
21280 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
21290 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
212a0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
212b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
212c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
212d0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
212e0 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
212f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21300 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
21310 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
21320 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
21330 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
21340 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
21350 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
21360 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
21370 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
21380 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
21390 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
213a0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
213b0 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
213c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
213d0 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
213e0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
213f0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
21400 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
21410 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
21420 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
21430 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
21440 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
21450 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
21460 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
21470 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
21480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21490 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
214a0 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
214b0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
214c0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
214d0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
214e0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
214f0 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
21500 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
21510 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
21520 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
21530 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
21540 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
21550 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21560 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
21570 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
21580 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
21590 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
215a0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
215b0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
215c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
215d0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
215e0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
215f0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
21600 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
21610 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
21620 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
21630 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
21640 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
21650 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
21660 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
21670 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
21680 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
21690 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
216a0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
216b0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
216c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
216d0 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
216e0 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
216f0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
21700 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
21710 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
21720 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
21730 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
21740 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
21750 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
21760 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
21770 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
21780 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
21790 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
217a0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
217b0 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
217c0 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
217d0 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
217e0 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
217f0 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
21800 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
21810 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
21820 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
21830 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
21840 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
21850 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
21860 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
21870 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
21880 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
21890 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
218a0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
218b0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
218c0 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
218d0 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
218e0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
218f0 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
21900 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
21910 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
21920 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
21930 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
21940 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
21950 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
21960 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
21970 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
21980 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
21990 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
219a0 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
219b0 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
219c0 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
219d0 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
219e0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
219f0 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
21a00 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
21a10 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
21a20 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
21a30 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
21a40 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
21a50 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
21a60 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
21a70 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
21a80 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
21a90 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
21aa0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
21ab0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
21ac0 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
21ad0 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
21ae0 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
21af0 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
21b00 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
21b10 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
21b20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
21b30 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
21b40 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
21b50 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
21b60 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
21b70 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
21b80 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
21b90 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
21ba0 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
21bb0 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
21bc0 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
21bd0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
21be0 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
21bf0 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
21c00 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
21c10 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
21c20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
21c30 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
21c40 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
21c50 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
21c60 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
21c70 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
21c80 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
21c90 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
21ca0 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
21cb0 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
21cc0 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
21cd0 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
21ce0 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
21cf0 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
21d00 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
21d10 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
21d20 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
21d30 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
21d40 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
21d50 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
21d60 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
21d70 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
21d80 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
21d90 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
21da0 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
21db0 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
21dc0 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
21dd0 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
21de0 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
21df0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
21e00 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
21e10 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
21e20 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
21e30 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
21e40 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
21e50 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
21e60 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
21e70 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
21e80 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
21e90 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
21ea0 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
21eb0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
21ec0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
21ed0 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
21ee0 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
21ef0 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77  path. .** ^(On w
21f00 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73  indows, the firs
21f10 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
21f20 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20  n absolute path 
21f30 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73  .** is a drive s
21f40 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e  pecification (e.
21f50 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a  g. "C:").)^.**.*
21f60 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
21f70 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
21f80 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
21f90 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
21fa0 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
21fb0 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
21fc0 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
21fd0 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
21fe0 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
21ff0 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
22000 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
22010 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64  ]..** SQLite and
22020 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56   its built-in [V
22030 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20  FSes] interpret 
22040 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  the.** following
22050 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
22060 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
22070 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f     <li> <b>vfs</
22080 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70  b>: ^The "vfs" p
22090 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
220a0 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
220b0 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20  the name of.**  
220c0 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20     a VFS object 
220d0 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68  that provides th
220e0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
220f0 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
22100 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20  t should.**     
22110 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73  be used to acces
22120 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
22130 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66  ile on disk. ^If
22140 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
22150 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e  set to.**     an
22160 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68   empty string th
22170 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62  e default VFS ob
22180 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53  ject is used. ^S
22190 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
221a0 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20  nown.**     VFS 
221b0 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66  is an error. ^If
221c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
221d0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
221e0 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73  he vfs option is
221f0 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c  .**     present,
22200 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70   then the VFS sp
22210 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
22220 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63  ption takes prec
22230 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20  edence over.**  
22240 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73     the value pas
22250 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
22260 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
22270 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22280 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
22290 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68  b>mode</b>: ^(Th
222a0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
222b0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
222c0 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22  ither "ro", "rw"
222d0 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20  ,.**     "rwc", 
222e0 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74  or "memory". Att
222f0 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69  empting to set i
22300 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76  t to any other v
22310 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61  alue is.**     a
22320 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20  n error)^. .**  
22330 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73     ^If "ro" is s
22340 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74  pecified, then t
22350 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
22360 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f  pened for read-o
22370 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  nly .**     acce
22380 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74  ss, just as if t
22390 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
223a0 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68  READONLY] flag h
223b0 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74  ad been set in t
223c0 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64  he .**     third
223d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
223e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
223f0 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
22400 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a  ion is set to .*
22410 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e  *     "rw", then
22420 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
22430 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
22440 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20  -write (but not 
22450 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20  create) .**     
22460 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51  access, as if SQ
22470 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
22480 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c  ITE (but not SQL
22490 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29  ITE_OPEN_CREATE)
224a0 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65   had .**     bee
224b0 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72  n set. ^Value "r
224c0 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  wc" is equivalen
224d0 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74  t to setting bot
224e0 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  h .**     SQLITE
224f0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
22500 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  and SQLITE_OPEN_
22510 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65  CREATE.  ^If the
22520 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a   mode option is.
22530 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d  **     set to "m
22540 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75  emory" then a pu
22550 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  re [in-memory da
22560 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76  tabase] that nev
22570 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20  er reads.**     
22580 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64  or writes from d
22590 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74  isk is used. ^It
225a0 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20   is an error to 
225b0 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20  specify a value 
225c0 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d  for.**     the m
225d0 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  ode parameter th
225e0 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72  at is less restr
225f0 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74  ictive than that
22600 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
22610 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70       the flags p
22620 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69  assed in the thi
22630 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
22640 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22650 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
22660 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54  <b>cache</b>: ^T
22670 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
22680 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
22690 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22   either "shared"
226a0 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76   or.**     "priv
226b0 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69  ate". ^Setting i
226c0 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73  t to "shared" is
226d0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
226e0 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  etting the.**   
226f0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48    SQLITE_OPEN_SH
22700 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e  AREDCACHE bit in
22710 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
22720 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a  ent passed to.**
22730 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65       sqlite3_ope
22740 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67  n_v2(). ^Setting
22750 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d   the cache param
22760 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65  eter to "private
22770 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75  " is .**     equ
22780 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
22790 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  ng the SQLITE_OP
227a0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
227b0 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20  bit..**     ^If 
227c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
227d0 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
227e0 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65  e "cache" parame
227f0 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69  ter is present i
22800 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66  n.**     a URI f
22810 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c  ilename, its val
22820 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79  ue overrides any
22830 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73   behavior reques
22840 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a  ted by setting.*
22850 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
22860 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f  N_PRIVATECACHE o
22870 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  r SQLITE_OPEN_SH
22880 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a  AREDCACHE flag..
22890 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70  **.**  <li> <b>p
228a0 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73  sow</b>: ^The ps
228b0 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64  ow parameter ind
228c0 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f  icates whether o
228d0 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20  r not the.**    
228e0 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72   [powersafe over
228f0 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20  write] property 
22900 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74  does or does not
22910 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a   apply to the.**
22920 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64       storage med
22930 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20  ia on which the 
22940 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65  database file re
22950 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  sides..**.**  <l
22960 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e  i> <b>nolock</b>
22970 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61  : ^The nolock pa
22980 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
22990 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d  lean query param
229a0 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63  eter.**     whic
229b0 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65  h if set disable
229c0 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69  s file locking i
229d0 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e  n rollback journ
229e0 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a  al modes.  This.
229f0 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c  **     is useful
22a00 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61   for accessing a
22a10 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66   database on a f
22a20 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64  ilesystem that d
22a30 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73  oes not.**     s
22a40 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20  upport locking. 
22a50 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62   Caution:  Datab
22a60 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d  ase corruption m
22a70 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74  ight result if t
22a80 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72  wo.**     or mor
22a90 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74  e processes writ
22aa0 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  e to the same da
22ab0 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f  tabase and any o
22ac0 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20  ne of those.**  
22ad0 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65     processes use
22ae0 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a  s nolock=1..**.*
22af0 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74  *  <li> <b>immut
22b00 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69  able</b>: ^The i
22b10 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74  mmutable paramet
22b20 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
22b30 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72  query.**     par
22b40 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69  ameter that indi
22b50 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64  cates that the d
22b60 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
22b70 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20  stored on.**    
22b80 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
22b90 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62  .  ^When immutab
22ba0 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74  le is set, SQLit
22bb0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
22bc0 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61  he.**     databa
22bd0 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62  se file cannot b
22be0 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20  e changed, even 
22bf0 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74  by a process wit
22c00 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20  h higher.**     
22c10 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73  privilege, and s
22c20 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  o the database i
22c30 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e  s opened read-on
22c40 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69  ly and all locki
22c50 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68  ng.**     and ch
22c60 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69  ange detection i
22c70 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75  s disabled.  Cau
22c80 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68  tion: Setting th
22c90 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20  e immutable.**  
22ca0 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61     property on a
22cb0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
22cc0 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74  hat does in fact
22cd0 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75   change can resu
22ce0 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63  lt.**     in inc
22cf0 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73  orrect query res
22d00 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  ults and/or [SQL
22d10 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72  ITE_CORRUPT] err
22d20 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20  ors..**     See 
22d30 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
22d40 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a  CAP_IMMUTABLE]..
22d50 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75  **       .** </u
22d60 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66  l>.**.** ^Specif
22d70 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20  ying an unknown 
22d80 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
22d90 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
22da0 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74   of a URI is not
22db0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46   an.** error.  F
22dc0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
22dd0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75  f SQLite might u
22de0 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69  nderstand additi
22df0 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61  onal query.** pa
22e00 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22  rameters.  See "
22e10 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72  [query parameter
22e20 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d  s with special m
22e30 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65  eaning to SQLite
22e40 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  ]" for.** additi
22e50 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
22e60 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
22e70 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d  lename examples]
22e80 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61  ] <h3>URI filena
22e90 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e  me examples</h3>
22ea0 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  .**.** <table bo
22eb0 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63  rder="1" align=c
22ec0 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e  enter cellpaddin
22ed0 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  g=5>.** <tr><th>
22ee0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c   URI filenames <
22ef0 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c  th> Results.** <
22f00 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
22f10 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
22f20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
22f30 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
22f40 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
22f50 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e  rectory..** <tr>
22f60 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
22f70 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e  fred/data.db<br>
22f80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
22f90 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  e:///home/fred/d
22fa0 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20  ata.db <br> .** 
22fb0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
22fc0 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66  localhost/home/f
22fd0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
22fe0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
22ff0 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61     Open the data
23000 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65  base file "/home
23010 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a  /fred/data.db"..
23020 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
23030 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65  ://darkstar/home
23040 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74  /fred/data.db <t
23050 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
23060 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73  An error. "darks
23070 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65  tar" is not a re
23080 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69  cognized authori
23090 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73  ty..** <tr><td s
230a0 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63  tyle="white-spac
230b0 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20  e:nowrap"> .**  
230c0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
230d0 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61  C:/Documents%20a
230e0 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72  nd%20Settings/fr
230f0 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e  ed/Desktop/data.
23100 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57  db.**     <td> W
23110 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65  indows only: Ope
23120 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
23130 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64  .db" on fred's d
23140 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a  esktop on drive.
23150 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20  **          C:. 
23160 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32  Note that the %2
23170 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68  0 escaping in th
23180 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f  is example is no
23190 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20  t strictly .**  
231a0 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72          necessar
231b0 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63  y - space charac
231c0 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  ters can be used
231d0 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20   literally.**   
231e0 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69         in URI fi
231f0 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e  lenames..** <tr>
23200 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
23210 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d  b?mode=ro&cache=
23220 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a  private <td> .**
23230 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
23240 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
23250 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
23260 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d  ectory for read-
23270 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20  only access..** 
23280 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c           Regardl
23290 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
232a0 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63  r not shared-cac
232b0 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  he mode is enabl
232c0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
232d0 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61    default, use a
232e0 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a   private cache..
232f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
23300 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
23310 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74  .db?vfs=unix-dot
23320 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  file <td>.**    
23330 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
23340 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
23350 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
23360 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
23370 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20  dotfile".**     
23380 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64       that uses d
23390 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63  ot-files in plac
233a0 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73  e of posix advis
233b0 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20  ory locking..** 
233c0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
233d0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
233e0 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
233f0 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
23400 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
23410 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
23420 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
23430 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
23440 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
23450 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
23460 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
23470 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
23480 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
23490 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
234a0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
234b0 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
234c0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
234d0 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
234e0 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
234f0 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
23500 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
23510 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
23520 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
23530 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
23540 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
23550 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
23560 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
23570 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
23580 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
23590 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
235a0 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
235b0 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
235c0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
235d0 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
235e0 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
235f0 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
23600 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
23610 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
23620 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
23630 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
23640 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
23650 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
23660 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
23670 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
23680 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
23690 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
236a0 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
236b0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
236c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
236d0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
236e0 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
236f0 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
23700 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
23710 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
23720 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
23730 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
23740 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
23750 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
23760 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
23770 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
23780 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
23790 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
237a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
237b0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
237c0 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  to Windows Runti
237d0 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  me users:</b>  T
237e0 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72  he temporary dir
237f0 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73  ectory must be s
23800 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  et.** prior to c
23810 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f  alling sqlite3_o
23820 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
23830 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68  _open_v2().  Oth
23840 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a  erwise, various.
23850 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74  ** features that
23860 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65   require the use
23870 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69   of temporary fi
23880 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a  les may fail..**
23890 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
238a0 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
238b0 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71  ctory].*/.int sq
238c0 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
238d0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
238e0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
238f0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
23900 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
23910 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
23920 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
23930 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
23940 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
23950 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
23960 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
23970 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
23980 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
23990 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
239a0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
239b0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
239c0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
239d0 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
239e0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
239f0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
23a00 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
23a10 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
23a20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
23a30 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
23a40 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
23a50 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
23a60 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
23a70 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
23a80 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
23a90 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
23aa0 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
23ab0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23ac0 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f  Obtain Values Fo
23ad0 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73  r URI Parameters
23ae0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
23af0 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65   utility routine
23b00 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  s, useful to VFS
23b10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
23b20 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20  , that check.** 
23b30 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61  to see if a data
23b40 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20  base file was a 
23b50 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  URI that contain
23b60 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75  ed a specific qu
23b70 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ery .** paramete
23b80 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74  r, and if so obt
23b90 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  ains the value o
23ba0 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72  f that query par
23bb0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
23bc0 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61   F is the databa
23bd0 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  se filename poin
23be0 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
23bf0 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68  the xOpen() meth
23c00 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20  od of .** a VFS 
23c10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
23c20 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61  hen the flags pa
23c30 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
23c40 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a  () has one or .*
23c50 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
23c60 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
23c70 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
23c80 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65  MAIN_DB] bits se
23c90 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68  t and.** P is th
23ca0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75  e name of the qu
23cb0 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ery parameter, t
23cc0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  hen.** sqlite3_u
23cd0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
23ce0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  ) returns the va
23cf0 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20  lue of the P.** 
23d00 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20  parameter if it 
23d10 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c  exists or a NULL
23d20 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f   pointer if P do
23d30 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73  es not appear as
23d40 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   a .** query par
23d50 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66  ameter on F.  If
23d60 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61   P is a query pa
23d70 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20  rameter of F.** 
23d80 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20  has no explicit 
23d90 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69  value, then sqli
23da0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
23db0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a  r(F,P) returns.*
23dc0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
23dd0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
23de0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
23df0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
23e00 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73  P,B) routine ass
23e10 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61  umes that P is a
23e20 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61   boolean.** para
23e30 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
23e40 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61  s true (1) or fa
23e50 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e  lse (0) accordin
23e60 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a  g to the value.*
23e70 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c  * of P.  The sql
23e80 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
23e90 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
23ea0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
23eb0 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65   if the.** value
23ec0 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65   of query parame
23ed0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
23ee0 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f  "yes", "true", o
23ef0 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a  r "on" in any.**
23f00 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20   case or if the 
23f10 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
23f20 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d  h a non-zero num
23f30 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71  ber.  The .** sq
23f40 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
23f50 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
23f60 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  s returns false 
23f70 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65  (0) if the value
23f80 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   of.** query par
23f90 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
23fa0 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22  of "no", "false"
23fb0 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e  , or "off" in an
23fc0 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20  y case or.** if 
23fd0 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
23fe0 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20   with a numeric 
23ff0 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e  zero.  If P is n
24000 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61  ot a query.** pa
24010 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20  rameter on F or 
24020 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  if the value of 
24030 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61  P is does not ma
24040 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a  tch any of the.*
24050 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71  * above, then sq
24060 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
24070 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
24080 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54   (B!=0)..**.** T
24090 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  he sqlite3_uri_i
240a0 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74  nt64(F,P,D) rout
240b0 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ine converts the
240c0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f   value of P into
240d0 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67   a.** 64-bit sig
240e0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
240f0 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74  returns that int
24100 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20  eger, or D if P 
24110 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73  does not.** exis
24120 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65  t.  If the value
24130 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69   of P is somethi
24140 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e  ng other than an
24150 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a   integer, then.*
24160 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  * zero is return
24170 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20  ed..** .** If F 
24180 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
24190 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
241a0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
241b0 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  P) returns NULL 
241c0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
241d0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
241e0 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66  ) returns B.  If
241f0 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c   F is not a NULL
24200 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20   pointer and.** 
24210 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
24220 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  e file pathname 
24230 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
24240 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ite passed into 
24250 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53  the xOpen.** VFS
24260 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
24270 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
24280 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e  is routine is un
24290 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
242a0 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61  ably.** undesira
242b0 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ble..*/.const ch
242c0 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f  ar *sqlite3_uri_
242d0 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
242e0 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
242f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
24300 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ram);.int sqlite
24310 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f  3_uri_boolean(co
24320 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
24330 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
24340 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c  ram, int bDefaul
24350 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  t);.sqlite3_int6
24360 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  4 sqlite3_uri_in
24370 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t64(const char*,
24380 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
24390 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a  lite3_int64);...
243a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
243b0 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
243c0 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e  Messages.**.** ^
243d0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
243e0 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
243f0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
24400 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
24410 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
24420 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
24430 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
24440 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
24450 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
24460 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
24470 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
24480 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
24490 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
244a0 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
244b0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
244c0 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
244d0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
244e0 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
244f0 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
24500 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71  efined.  ^The sq
24510 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
24520 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
24530 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
24540 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
24550 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
24560 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
24570 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
24580 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
24590 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
245a0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
245b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
245c0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
245d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
245e0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
245f0 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
24600 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
24610 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
24620 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
24630 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
24640 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
24650 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
24660 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
24670 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
24680 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
24690 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
246a0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
246b0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
246c0 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
246d0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
246e0 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
246f0 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
24700 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
24710 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
24720 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
24730 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
24740 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
24750 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
24760 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63  rrstr() interfac
24770 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e  e returns the En
24780 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
24790 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63  ext.** that desc
247a0 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c  ribes the [resul
247b0 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d  t code], as UTF-
247c0 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  8..** ^(Memory t
247d0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
247e0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
247f0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
24800 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73  nally.** and mus
24810 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62  t not be freed b
24820 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
24830 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  n)^..**.** When 
24840 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
24850 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
24860 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
24870 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
24880 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
24890 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
248a0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
248b0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
248c0 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
248d0 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
248e0 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
248f0 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
24900 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
24910 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
24920 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
24930 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
24940 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
24950 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
24960 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
24970 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
24980 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
24990 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
249a0 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
249b0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
249c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
249d0 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
249e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
249f0 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
24a00 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
24a10 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
24a20 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
24a30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
24a40 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
24a50 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
24a60 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
24a70 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
24a80 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
24a90 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
24aa0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
24ab0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
24ac0 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
24ad0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
24ae0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
24af0 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
24b00 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
24b10 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
24b20 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
24b30 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
24b40 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
24b50 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
24b60 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
24b70 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
24b80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
24b90 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
24ba0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
24bb0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
24bc0 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
24bd0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
24be0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
24bf0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
24c00 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
24c10 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
24c20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
24c30 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
24c40 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
24c50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24c60 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
24c70 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
24c80 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
24c90 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
24ca0 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
24cb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
24cc0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
24cd0 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
24ce0 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
24cf0 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
24d00 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
24d10 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
24d20 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
24d30 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
24d40 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
24d50 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
24d60 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
24d70 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
24d80 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
24d90 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
24da0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24db0 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
24dc0 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
24dd0 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
24de0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
24df0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
24e00 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
24e10 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
24e20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
24e30 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
24e40 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
24e50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
24e60 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
24e70 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
24e80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
24e90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
24ea0 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
24eb0 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
24ec0 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
24ed0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
24ee0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
24ef0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
24f00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
24f10 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
24f20 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
24f30 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
24f40 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
24f50 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
24f60 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
24f70 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
24f80 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24f90 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
24fa0 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
24fb0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
24fc0 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
24fd0 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
24fe0 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
24ff0 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
25000 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
25010 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
25020 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
25030 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
25040 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
25050 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
25060 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
25070 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
25080 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
25090 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
250a0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
250b0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
250c0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
250d0 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
250e0 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
250f0 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
25100 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
25110 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
25120 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
25130 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
25140 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
25150 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
25160 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
25170 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
25180 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
25190 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
251a0 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
251b0 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
251c0 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
251d0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
251e0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
251f0 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
25200 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
25210 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
25220 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
25230 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
25240 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
25250 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
25260 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
25270 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
25280 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
25290 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
252a0 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
252b0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
252c0 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
252d0 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
252e0 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
252f0 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
25300 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
25310 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
25320 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
25330 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
25340 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
25350 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
25360 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
25370 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
25380 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
25390 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
253a0 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
253b0 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
253c0 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
253d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
253e0 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
253f0 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
25400 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
25410 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
25420 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
25430 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
25440 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
25450 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
25460 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
25470 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
25480 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
25490 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
254a0 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
254b0 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
254c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
254d0 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
254e0 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
254f0 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
25500 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
25510 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
25520 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
25530 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
25540 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
25550 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
25560 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
25570 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
25580 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
25590 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
255a0 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
255b0 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
255c0 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
255d0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
255e0 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
255f0 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
25600 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
25610 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
25620 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
25630 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
25640 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
25650 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
25660 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
25670 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
25680 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
25690 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
256a0 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
256b0 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
256c0 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
256d0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
256e0 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
256f0 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
25700 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
25710 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
25720 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
25730 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
25740 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
25750 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
25760 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
25770 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
25780 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
25790 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
257a0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
257b0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
257c0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
257d0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
257e0 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
257f0 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
25800 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
25810 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
25820 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
25830 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
25840 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
25850 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
25860 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
25870 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
25880 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
25890 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
258a0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
258b0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
258c0 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
258d0 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
258e0 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
258f0 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
25900 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25910 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
25920 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
25930 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
25940 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
25950 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
25960 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
25970 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
25980 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25990 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
259a0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
259b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
259c0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
259d0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
259e0 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
259f0 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
25a00 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
25a10 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25a20 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
25a30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
25a40 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
25a50 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
25a60 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
25a70 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
25a80 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
25a90 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
25aa0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
25ab0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
25ac0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
25ad0 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
25ae0 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
25af0 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
25b00 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25b10 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
25b20 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
25b30 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
25b40 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
25b50 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
25b60 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
25b70 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
25b80 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
25b90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25ba0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
25bb0 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
25bc0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
25bd0 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
25be0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25bf0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
25c00 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
25c10 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
25c20 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
25c30 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
25c40 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
25c50 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
25c60 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
25c70 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
25c80 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
25c90 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
25ca0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
25cb0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
25cc0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
25cd0 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
25ce0 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
25cf0 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
25d00 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
25d10 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
25d20 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
25d30 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
25d40 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
25d50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
25d60 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
25d70 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
25d80 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
25d90 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25da0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
25db0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
25dc0 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
25dd0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25de0 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
25df0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25e00 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
25e10 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25e20 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
25e30 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
25e40 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
25e50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25e60 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
25e70 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
25e80 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25e90 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
25ea0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
25eb0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
25ec0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
25ed0 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
25ee0 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
25ef0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
25f00 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
25f10 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
25f20 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
25f30 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
25f40 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
25f50 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
25f60 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
25f70 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
25f80 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
25f90 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
25fa0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
25fb0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
25fc0 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
25fd0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
25fe0 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
25ff0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26000 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
26010 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
26020 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ers.</dd>)^.**.*
26030 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26040 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d  _WORKER_THREADS]
26050 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26060 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
26070 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ADS</dt>.** <dd>
26080 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
26090 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20  er of auxiliary 
260a0 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74  worker threads t
260b0 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20  hat a single.** 
260c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
260d0 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c  ent] may start.<
260e0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
260f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
26100 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
26110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26120 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
26130 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
26140 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
26150 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
26160 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
26170 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26180 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
26190 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
261a0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
261b0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
261c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
261d0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
261e0 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
261f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
26200 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
26210 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
26220 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
26230 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
26240 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
26250 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
26260 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
26270 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
26280 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26290 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
262a0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
262b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
262c0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
262d0 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
262e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
262f0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
26300 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
26310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26320 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
26330 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a  S           11..
26340 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26350 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
26360 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
26370 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
26380 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
26390 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
263a0 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
263b0 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
263c0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
263d0 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
263e0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
263f0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
26400 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
26410 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
26420 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
26430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
26440 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
26450 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
26460 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
26470 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
26480 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
26490 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
264a0 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
264b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
264c0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
264d0 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
264e0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
264f0 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
26500 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
26510 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
26520 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
26530 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
26540 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
26550 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
26560 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
26570 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
26580 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
26590 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
265a0 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
265b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
265c0 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
265d0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
265e0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
265f0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
26600 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
26610 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
26620 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
26630 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
26640 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
26650 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
26660 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
26670 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
26680 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
26690 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e  ^When nByte is n
266a0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
266b0 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
266c0 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
266d0 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
266e0 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
266f0 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
26700 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
26710 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
26720 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
26730 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
26740 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
26750 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
26760 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
26770 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
26780 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
26790 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
267a0 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
267b0 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
267c0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
267d0 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
267e0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
267f0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
26800 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
26810 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
26820 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74  nator bytes as t
26830 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65  his saves SQLite
26840 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a   from having to.
26850 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f  ** make a copy o
26860 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
26870 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  ng..**.** ^If pz
26880 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
26890 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
268a0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
268b0 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
268c0 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
268d0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
268e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
268f0 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
26900 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
26910 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
26920 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
26930 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
26940 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
26950 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
26960 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
26970 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
26980 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
26990 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
269a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
269b0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
269c0 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
269d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
269e0 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
269f0 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
26a00 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
26a10 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
26a20 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
26a30 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
26a40 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
26a50 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
26a60 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
26a70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
26a80 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
26a90 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
26aa0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
26ab0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
26ac0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
26ad0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
26ae0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
26af0 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
26b00 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
26b10 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
26b20 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
26b30 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
26b40 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
26b50 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
26b60 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
26b70 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
26b80 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
26b90 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
26ba0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
26bb0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
26bc0 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
26bd0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
26be0 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
26bf0 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
26c00 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
26c10 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
26c20 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
26c30 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
26c40 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
26c50 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
26c60 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
26c70 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
26c80 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
26c90 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
26ca0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
26cb0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
26cc0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
26cd0 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
26ce0 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
26cf0 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
26d00 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
26d10 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
26d20 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
26d30 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
26d40 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
26d50 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
26d60 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
26d70 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
26d80 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
26d90 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
26da0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
26db0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
26dc0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
26dd0 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
26de0 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
26df0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
26e00 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
26e10 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
26e20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
26e30 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c   As many as [SQL
26e40 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52  ITE_MAX_SCHEMA_R
26e50 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73  ETRY].** retries
26e60 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f   will occur befo
26e70 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  re sqlite3_step(
26e80 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72  ) gives up and r
26e90 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e  eturns an error.
26ea0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
26eb0 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
26ec0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
26ed0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
26ee0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
26ef0 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
26f00 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
26f10 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
26f20 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
26f30 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
26f40 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
26f50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
26f60 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
26f70 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
26f80 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
26f90 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
26fa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
26fb0 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
26fc0 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
26fd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
26fe0 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
26ff0 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
27000 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
27010 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
27020 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
27030 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
27040 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
27050 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
27060 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
27070 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
27080 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
27090 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
270a0 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
270b0 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
270c0 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
270d0 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
270e0 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
270f0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
27100 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
27110 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
27120 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
27130 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
27140 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
27150 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
27160 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
27170 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
27180 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
27190 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
271a0 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
271b0 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
271c0 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
271d0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
271e0 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
271f0 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
27200 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
27210 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
27220 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
27230 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
27240 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
27250 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
27260 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
27270 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
27280 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
27290 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
272a0 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
272b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
272c0 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
272d0 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
272e0 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
272f0 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d  NABLE_STAT3] com
27300 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
27310 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
27320 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
27330 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
27340 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
27350 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
27360 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
27370 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
27380 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
27390 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
273a0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
273b0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
273c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
273d0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
273e0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
273f0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
27400 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
27410 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
27420 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
27430 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
27440 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
27450 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
27460 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
27470 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
27480 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
27490 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
274a0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
274b0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
274c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
274d0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
274e0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
274f0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
27500 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
27510 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
27520 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
27530 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
27540 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
27550 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
27560 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
27570 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
27580 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
27590 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
275a0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
275b0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
275c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
275d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
275e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
275f0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
27600 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
27610 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
27620 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
27630 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
27640 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
27650 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
27660 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
27670 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
27680 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
27690 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
276a0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
276b0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
276c0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
276d0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
276e0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
276f0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
27700 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
27710 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
27720 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
27730 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
27740 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
27750 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
27760 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
27770 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
27780 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
27790 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
277a0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
277b0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
277c0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
277d0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
277e0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
277f0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
27800 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
27810 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
27820 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
27830 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
27840 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
27850 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
27860 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
27870 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  SQL.**.** ^This 
27880 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
27890 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
278a0 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
278b0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
278c0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
278d0 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
278e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
278f0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
27900 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
27910 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
27920 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27930 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
27940 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
27950 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
27960 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
27970 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
27980 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
27990 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
279a0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
279b0 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
279c0 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54  atabase.**.** ^T
279d0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
279e0 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
279f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
27a00 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
27a10 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
27a20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
27a30 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
27a40 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
27a50 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
27a60 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
27a70 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
27a80 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
27a90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
27aa0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
27ab0 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
27ac0 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
27ad0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
27ae0 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
27af0 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
27b00 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
27b10 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
27b20 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
27b30 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
27b40 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
27b50 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
27b60 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
27b70 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
27b80 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
27b90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27ba0 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
27bb0 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
27bc0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
27bd0 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
27be0 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
27bf0 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
27c00 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
27c10 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
27c20 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
27c30 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
27c40 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
27c50 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
27c60 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
27c70 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
27c80 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
27c90 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
27ca0 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
27cb0 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
27cc0 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
27cd0 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
27ce0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
27cf0 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
27d00 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
27d10 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
27d20 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
27d30 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
27d40 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
27d50 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
27d60 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
27d70 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
27d80 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
27d90 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
27da0 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
27db0 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
27dc0 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
27dd0 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
27de0 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
27df0 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
27e00 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
27e10 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
27e20 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
27e30 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
27e40 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
27e50 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
27e60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
27e70 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
27e80 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
27e90 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
27ea0 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
27eb0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
27ec0 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
27ed0 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  k..*/.int sqlite
27ee0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
27ef0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
27f00 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
27f10 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
27f20 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
27f30 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
27f40 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  n Reset.**.** ^T
27f50 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
27f60 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
27f70 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
27f80 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
27f90 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
27fa0 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
27fb0 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
27fc0 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
27fd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
27fe0 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f  p(S)] but has no
27ff0 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  t run to complet
28000 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e  ion and/or has n
28010 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65  ot .** been rese
28020 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
28030 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68  _reset(S)].  ^Th
28040 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
28050 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66  usy(S).** interf
28060 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
28070 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c  e if S is a NULL
28080 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20   pointer.  If S 
28090 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c  is not a .** NUL
280a0 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73  L pointer and is
280b0 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74   not a pointer t
280c0 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61  o a valid [prepa
280d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
280e0 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74  * object, then t
280f0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
28100 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
28110 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
28120 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
28130 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
28140 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69  sed in combinati
28150 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  on [sqlite3_next
28160 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c  _stmt()].** to l
28170 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72  ocate all prepar
28180 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
28190 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
281a0 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e  database .** con
281b0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65  nection that are
281c0 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e   in need of bein
281d0 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63  g reset.  This c
281e0 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66  an be used,.** f
281f0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64  or example, in d
28200 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e  iagnostic routin
28210 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72  es to search for
28220 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74   prepared .** st
28230 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  atements that ar
28240 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e  e holding a tran
28250 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f  saction open..*/
28260 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
28270 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73  t_busy(sqlite3_s
28280 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
28290 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
282a0 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
282b0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
282c0 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
282d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
282e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
282f0 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
28300 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
28310 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28320 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
28330 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
28340 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
28350 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
28360 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
28370 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
28380 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
28390 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
283a0 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
283b0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
283c0 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
283d0 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
283e0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
283f0 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
28400 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
28410 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
28420 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
28430 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
28440 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
28450 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
28460 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
28470 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
28480 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
28490 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
284a0 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
284b0 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
284c0 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
284d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
284e0 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
284f0 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
28500 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
28510 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
28520 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
28530 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
28540 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
28550 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
28560 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
28570 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
28580 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
28590 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
285a0 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
285b0 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
285c0 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
285d0 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
285e0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
285f0 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
28600 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
28610 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
28620 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
28630 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
28640 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
28650 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
28660 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
28670 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
28680 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
28690 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
286a0 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
286b0 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
286c0 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
286d0 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
286e0 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
286f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
28700 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
28710 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
28720 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
28730 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
28740 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
28750 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
28760 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
28770 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28780 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
28790 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
287a0 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
287b0 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
287c0 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
287d0 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
287e0 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
287f0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
28800 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
28810 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
28820 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
28830 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
28840 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
28850 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
28860 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
28870 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
28880 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28890 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
288a0 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
288b0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
288c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
288d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
288e0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
288f0 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
28900 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
28910 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
28920 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
28930 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
28940 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
28950 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
28960 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28970 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
28980 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
28990 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
289a0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
289b0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
289c0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
289d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
289e0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
289f0 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
28a00 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
28a10 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
28a20 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28a30 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
28a40 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
28a50 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
28a60 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
28a70 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
28a80 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
28a90 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
28aa0 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
28ab0 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
28ac0 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
28ad0 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
28ae0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
28af0 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
28b00 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
28b10 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
28b20 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
28b30 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
28b40 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
28b50 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
28b60 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
28b70 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
28b80 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
28b90 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
28ba0 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
28bb0 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
28bc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
28bd0 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
28be0 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
28bf0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
28c00 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
28c10 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
28c20 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
28c30 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
28c40 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
28c50 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
28c60 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
28c70 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
28c80 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
28c90 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
28ca0 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
28cb0 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
28cc0 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
28cd0 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
28ce0 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
28cf0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
28d00 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
28d10 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
28d20 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
28d30 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
28d40 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
28d50 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
28d60 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
28d70 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ding}.**.** ^(In
28d80 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
28d90 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
28da0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28db0 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
28dc0 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
28dd0 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
28de0 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
28df0 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
28e00 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
28e10 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
28e20 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
28e30 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
28e40 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
28e50 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
28e60 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
28e70 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
28e80 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
28e90 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
28ea0 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
28eb0 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
28ec0 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
28ed0 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
28ee0 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
28ef0 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
28f00 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
28f10 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
28f20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
28f30 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
28f40 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
28f50 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
28f60 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
28f70 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
28f80 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
28f90 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
28fa0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
28fb0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
28fc0 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
28fd0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
28fe0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
28ff0 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
29000 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
29010 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
29020 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
29030 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
29040 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
29050 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
29060 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
29070 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
29080 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
29090 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
290a0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
290b0 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
290c0 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
290d0 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
290e0 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
290f0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
29100 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
29110 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
29120 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
29130 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
29140 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
29150 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
29160 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
29170 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
29180 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
29190 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
291a0 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
291b0 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
291c0 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
291d0 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
291e0 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
291f0 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
29200 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
29210 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
29220 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
29230 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
29240 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
29250 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
29260 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
29270 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
29280 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
29290 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
292a0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
292b0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
292c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
292d0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
292e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
292f0 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
29300 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
29310 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
29320 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
29330 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
29340 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
29350 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
29360 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
29370 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
29380 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
29390 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
293a0 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
293b0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
293c0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
293d0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
293e0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
293f0 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
29400 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
29410 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
29420 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
29430 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
29440 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
29450 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
29460 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
29470 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
29480 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
29490 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
294a0 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
294b0 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
294c0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
294d0 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
294e0 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
294f0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
29500 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
29510 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
29520 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
29530 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
29540 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
29550 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
29560 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
29570 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
29580 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
29590 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
295a0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
295b0 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
295c0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
295d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
295e0 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a  d_text64() then.
295f0 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  ** that paramete
29600 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
29610 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
29620 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
29630 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
29640 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
29650 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
29660 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
29670 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
29680 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
29690 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
296a0 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
296b0 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
296c0 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
296d0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
296e0 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
296f0 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
29700 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
29710 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
29720 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
29730 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
29740 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
29750 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
29760 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
29770 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42  ment to the BLOB
29780 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64   and string bind
29790 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ing interfaces.*
297a0 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  * is a destructo
297b0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
297c0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
297d0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
297e0 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
297f0 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
29800 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
29810 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
29820 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
29830 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
29840 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
29850 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e   bind API fails.
29860 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
29870 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
29880 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
29890 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
298a0 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
298b0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
298c0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
298d0 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
298e0 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
298f0 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
29900 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
29910 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
29920 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
29930 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
29940 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
29950 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
29960 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
29970 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
29980 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
29990 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
299a0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
299b0 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
299c0 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67  * ^The sixth arg
299d0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
299e0 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d  _bind_text64() m
299f0 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a  ust be one of.**
29a00 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
29a10 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
29a20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
29a30 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
29a40 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63  16LE].** to spec
29a50 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ify the encoding
29a60 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20   of the text in 
29a70 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
29a80 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ter.  If.** the 
29a90 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
29aa0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
29ab0 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f  ext64() is not o
29ac0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c  ne of the.** all
29ad0 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77  owed values show
29ae0 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74  n above, or if t
29af0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
29b00 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a   is different.**
29b10 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69   from the encodi
29b20 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ng specified by 
29b30 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65  the sixth parame
29b40 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ter, then the be
29b50 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
29b60 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
29b70 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29b80 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
29b90 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
29ba0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
29bb0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
29bc0 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
29bd0 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
29be0 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
29bf0 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
29c00 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
29c10 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
29c20 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
29c30 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
29c40 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
29c50 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
29c60 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
29c70 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
29c80 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
29c90 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
29ca0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
29cb0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
29cc0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
29cd0 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
29ce0 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
29cf0 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
29d00 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
29d10 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
29d20 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
29d30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
29d40 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
29d50 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
29d60 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
29d70 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
29d80 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
29d90 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
29da0 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
29db0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
29dc0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
29dd0 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
29de0 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
29df0 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
29e00 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
29e10 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
29e20 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
29e30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
29e40 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
29e50 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
29e60 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
29e70 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
29e80 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
29e90 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
29ea0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
29eb0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
29ec0 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
29ed0 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
29ee0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
29ef0 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
29f00 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
29f10 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
29f20 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
29f30 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29f40 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
29f50 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
29f60 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
29f70 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
29f80 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
29f90 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
29fa0 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74  TE_TOOBIG] might
29fb0 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
29fc0 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74  the size of a st
29fd0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20  ring or BLOB.** 
29fe0 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69  exceeds limits i
29ff0 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  mposed by [sqlit
2a000 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2a010 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29  E_LIMIT_LENGTH])
2a020 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d   or.** [SQLITE_M
2a030 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e  AX_LENGTH]..** ^
2a040 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
2a050 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
2a060 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
2a070 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2a080 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
2a090 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
2a0a0 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
2a0b0 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
2a0c0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2a0d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2a0e0 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
2a0f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a100 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
2a110 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2a120 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2a130 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2a140 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
2a150 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2a160 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
2a170 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
2a180 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2a190 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69  bind_blob64(sqli
2a1a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2a1b0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c  const void*, sql
2a1c0 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
2a1d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a1e0 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
2a1f0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2a200 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
2a210 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a220 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
2a230 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
2a240 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a250 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
2a260 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
2a270 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a280 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
2a290 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
2a2a0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
2a2b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2a2c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a2d0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2a2e0 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  mt*,int,const ch
2a2f0 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28  ar*,int,void(*)(
2a300 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2a310 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2a320 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a330 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2a340 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2a350 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2a360 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2a370 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a380 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
2a390 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2a3a0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2a3b0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2a3c0 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e  )(void*), unsign
2a3d0 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67  ed char encoding
2a3e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2a3f0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
2a400 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2a410 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
2a420 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2a430 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
2a440 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a450 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
2a460 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2a470 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
2a480 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ters.**.** ^This
2a490 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2a4a0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
2a4b0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
2a4c0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
2a4d0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2a4e0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
2a4f0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
2a500 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
2a510 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
2a520 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
2a530 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
2a540 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
2a550 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
2a560 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
2a570 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2a580 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
2a590 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
2a5a0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
2a5b0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
2a5c0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
2a5d0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
2a5e0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
2a5f0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
2a600 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
2a610 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
2a620 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
2a630 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
2a640 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
2a650 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
2a660 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
2a670 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
2a680 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
2a690 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
2a6a0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
2a6b0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2a6c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2a6d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2a6e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a6f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2a700 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2a710 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a720 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2a730 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2a740 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2a750 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
2a760 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a770 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
2a780 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a  t Parameter.**.*
2a790 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2a7a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2a7b0 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
2a7c0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
2a7d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
2a7e0 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
2a7f0 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
2a800 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2a810 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
2a820 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2a830 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
2a840 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
2a850 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
2a860 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
2a870 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
2a880 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
2a890 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
2a8a0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
2a8b0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
2a8c0 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
2a8d0 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
2a8e0 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
2a8f0 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
2a900 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
2a910 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
2a920 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
2a930 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
2a940 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
2a950 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
2a960 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
2a970 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
2a980 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
2a990 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
2a9a0 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
2a9b0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
2a9c0 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
2a9d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
2a9e0 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
2a9f0 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
2aa00 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
2aa10 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
2aa20 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
2aa30 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
2aa40 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
2aa50 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
2aa60 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
2aa70 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
2aa80 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
2aa90 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
2aaa0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
2aab0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2aac0 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
2aad0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2aae0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
2aaf0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2ab00 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2ab10 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2ab20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ab30 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
2ab40 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2ab50 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2ab60 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
2ab70 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
2ab80 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2ab90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2aba0 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
2abb0 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
2abc0 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
2abd0 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
2abe0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2abf0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
2ac00 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
2ac10 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
2ac20 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
2ac30 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
2ac40 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
2ac50 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
2ac60 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2ac70 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2ac80 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
2ac90 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
2aca0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
2acb0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
2acc0 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
2acd0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
2ace0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
2acf0 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
2ad00 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2ad10 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
2ad20 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
2ad30 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
2ad40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2ad50 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2ad60 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2ad70 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2ad80 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2ad90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2ada0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2adb0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2adc0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2add0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
2ade0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2adf0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
2ae00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
2ae10 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
2ae20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ae30 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
2ae40 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
2ae50 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
2ae60 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
2ae70 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
2ae80 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
2ae90 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
2aea0 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
2aeb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2aec0 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
2aed0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2aee0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
2aef0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
2af00 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
2af10 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
2af20 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
2af30 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2af40 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2af50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2af60 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
2af70 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
2af80 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  t Set.**.** ^Ret
2af90 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
2afa0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2afb0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
2afc0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
2afd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2afe0 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
2aff0 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2b000 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
2b010 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
2b020 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
2b030 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
2b040 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
2b050 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2b060 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
2b070 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
2b080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2b090 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2b0a0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2b0b0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
2b0c0 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
2b0d0 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
2b0e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2b0f0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
2b100 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
2b110 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
2b120 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
2b130 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2b140 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
2b150 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2b160 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
2b170 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2b180 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2b190 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2b1a0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
2b1b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b1c0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
2b1d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2b1e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
2b1f0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
2b200 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
2b210 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2b220 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b230 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
2b240 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
2b250 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
2b260 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2b270 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
2b280 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
2b290 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2b2a0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
2b2b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
2b2c0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
2b2d0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
2b2e0 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
2b2f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b300 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
2b310 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
2b320 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2b330 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2b340 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2b350 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2b360 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2b370 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2b380 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2b390 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2b3a0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
2b3b0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2b3c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2b3d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2b3e0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
2b3f0 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
2b400 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
2b410 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
2b420 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
2b430 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
2b440 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
2b450 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
2b460 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
2b470 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
2b480 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
2b490 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2b4a0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2b4b0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
2b4c0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
2b4d0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
2b4e0 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
2b4f0 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
2b500 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
2b510 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
2b520 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
2b530 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
2b540 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
2b550 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
2b560 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
2b570 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
2b580 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
2b590 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f   the next..*/.co
2b5a0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2b5b0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
2b5c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b5d0 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
2b5e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2b5f0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2b600 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
2b610 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2b620 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
2b630 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2b640 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2b650 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
2b660 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
2b670 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
2b680 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
2b690 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
2b6a0 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
2b6b0 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
2b6c0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
2b6d0 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
2b6e0 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
2b6f0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
2b700 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
2b710 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
2b720 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
2b730 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
2b740 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2b750 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
2b760 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
2b770 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
2b780 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
2b790 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2b7a0 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
2b7b0 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
2b7c0 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
2b7d0 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
2b7e0 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
2b7f0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2b800 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
2b810 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b820 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
2b830 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2b840 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2b850 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2b860 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2b870 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2b880 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2b890 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2b8a0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2b8b0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2b8c0 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2b8d0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
2b8e0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
2b8f0 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
2b900 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
2b910 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2b920 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
2b930 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
2b940 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
2b950 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
2b960 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
2b970 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
2b980 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2b990 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
2b9a0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
2b9b0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2b9c0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2b9d0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2b9e0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
2b9f0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
2ba00 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
2ba10 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
2ba20 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
2ba30 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
2ba40 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
2ba50 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
2ba60 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
2ba70 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
2ba80 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
2ba90 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
2baa0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
2bab0 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
2bac0 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
2bad0 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
2bae0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
2baf0 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
2bb00 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2bb10 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
2bb20 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
2bb30 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
2bb40 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
2bb50 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
2bb60 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
2bb70 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
2bb80 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2bb90 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
2bba0 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
2bbb0 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
2bbc0 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
2bbd0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
2bbe0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
2bbf0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
2bc00 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
2bc10 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
2bc20 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
2bc30 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
2bc40 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
2bc50 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
2bc60 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
2bc70 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
2bc80 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
2bc90 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
2bca0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
2bcb0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
2bcc0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
2bcd0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
2bce0 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
2bcf0 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
2bd00 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2bd10 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2bd20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
2bd30 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
2bd40 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
2bd50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
2bd60 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
2bd70 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2bd80 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
2bd90 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2bda0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2bdb0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2bdc0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
2bdd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2bde0 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
2bdf0 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
2be00 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
2be10 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
2be20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
2be30 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
2be40 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
2be50 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2be60 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2be70 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
2be80 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2be90 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2bea0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2beb0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2bec0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2bed0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
2bee0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2bef0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
2bf00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2bf10 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
2bf20 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2bf30 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2bf40 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2bf50 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2bf60 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2bf70 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2bf80 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2bf90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2bfa0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2bfb0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2bfc0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
2bfd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2bfe0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2bff0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
2c000 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
2c010 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  Result.**.** ^(T
2c020 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2c030 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
2c040 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2c050 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
2c060 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
2c070 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2c080 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2c090 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
2c0a0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
2c0b0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
2c0c0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
2c0d0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
2c0e0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2c0f0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
2c100 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
2c110 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
2c120 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
2c130 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2c140 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2c150 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
2c160 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2c170 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
2c180 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2c190 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
2c1a0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2c1b0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
2c1c0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
2c1d0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
2c1e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2c1f0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
2c200 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
2c210 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
2c220 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
2c230 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
2c240 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
2c250 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
2c260 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
2c270 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
2c280 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
2c290 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
2c2a0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
2c2b0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
2c2c0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
2c2d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
2c2e0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
2c2f0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
2c300 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2c310 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
2c320 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
2c330 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
2c340 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
2c350 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
2c360 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
2c370 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
2c380 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
2c390 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
2c3a0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
2c3b0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
2c3c0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
2c3d0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
2c3e0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
2c3f0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
2c400 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
2c410 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
2c420 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
2c430 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
2c440 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
2c450 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
2c460 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
2c470 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2c480 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2c490 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
2c4a0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2c4b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2c4c0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
2c4d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2c4e0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2c4f0 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
2c500 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
2c510 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
2c520 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c530 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
2c540 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
2c550 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2c560 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2c570 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2c580 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2c590 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2c5a0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
2c5b0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
2c5c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c5d0 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
2c5e0 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
2c5f0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
2c600 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
2c610 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
2c620 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
2c630 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
2c640 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
2c650 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
2c660 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
2c670 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
2c680 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
2c690 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
2c6a0 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
2c6b0 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
2c6c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2c6d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2c6e0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2c6f0 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
2c700 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
2c710 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2c720 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2c730 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
2c740 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
2c750 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
2c760 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2c770 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
2c780 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
2c790 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2c7a0 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
2c7b0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2c7c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
2c7d0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2c7e0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2c7f0 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
2c800 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
2c810 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2c820 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
2c830 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2c840 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
2c850 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
2c860 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2c870 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
2c880 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
2c890 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2c8a0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
2c8b0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2c8c0 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
2c8d0 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
2c8e0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
2c8f0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
2c900 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
2c910 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
2c920 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
2c930 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
2c940 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
2c950 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
2c960 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
2c970 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
2c980 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2c990 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
2c9a0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
2c9b0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
2c9c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2c9d0 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
2c9e0 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
2c9f0 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
2ca00 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
2ca10 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
2ca20 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
2ca30 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
2ca40 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
2ca50 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
2ca60 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
2ca70 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
2ca80 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
2ca90 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
2caa0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2cab0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2cac0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
2cad0 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
2cae0 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
2caf0 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
2cb00 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
2cb10 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
2cb20 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
2cb30 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2cb40 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
2cb50 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2cb60 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
2cb70 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
2cb80 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
2cb90 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
2cba0 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
2cbb0 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
2cbc0 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
2cbd0 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
2cbe0 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
2cbf0 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
2cc00 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
2cc10 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
2cc20 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2cc30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2cc40 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
2cc50 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
2cc60 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
2cc70 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2cc80 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
2cc90 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
2cca0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
2ccb0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
2ccc0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
2ccd0 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
2cce0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2ccf0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2cd00 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
2cd10 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
2cd20 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
2cd30 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2cd40 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
2cd50 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
2cd60 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
2cd70 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2cd80 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
2cd90 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
2cda0 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
2cdb0 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
2cdc0 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
2cdd0 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
2cde0 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
2cdf0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2ce00 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
2ce10 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2ce20 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
2ce30 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2ce40 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
2ce50 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2ce60 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
2ce70 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
2ce80 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
2ce90 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
2cea0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2ceb0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
2cec0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
2ced0 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
2cee0 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
2cef0 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
2cf00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2cf10 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
2cf20 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
2cf30 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2cf40 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
2cf50 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
2cf60 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
2cf70 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
2cf80 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2cf90 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
2cfa0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
2cfb0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2cfc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2cfd0 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
2cfe0 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
2cff0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
2d000 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
2d010 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
2d020 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2d030 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
2d040 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
2d050 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
2d060 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d070 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
2d080 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
2d090 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
2d0a0 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
2d0b0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
2d0c0 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
2d0d0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
2d0e0 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
2d0f0 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
2d100 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
2d110 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
2d120 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
2d130 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
2d140 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
2d150 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
2d160 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
2d170 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
2d180 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20  t after version 
2d190 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
2d1a0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
2d1b0 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
2d1c0 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
2d1d0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
2d1e0 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
2d1f0 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
2d200 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2d210 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
2d220 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
2d230 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
2d240 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
2d250 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
2d260 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
2d270 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
2d280 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
2d290 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
2d2a0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
2d2b0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
2d2c0 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
2d2d0 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
2d2e0 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
2d2f0 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
2d300 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
2d310 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
2d320 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
2d330 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2d340 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
2d350 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
2d360 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
2d370 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
2d380 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
2d390 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
2d3a0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
2d3b0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
2d3c0 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
2d3d0 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
2d3e0 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
2d3f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2d400 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d410 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
2d420 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
2d430 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
2d440 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
2d450 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
2d460 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
2d470 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
2d480 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
2d490 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
2d4a0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
2d4b0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
2d4c0 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
2d4d0 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
2d4e0 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
2d4f0 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
2d500 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
2d510 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2d520 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2d530 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
2d540 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
2d550 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
2d560 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2d570 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2d580 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
2d590 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
2d5a0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2d5b0 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
2d5c0 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
2d5d0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2d5e0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2d5f0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2d600 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
2d610 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2d620 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
2d630 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2d640 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
2d650 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
2d660 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult set.**.** ^T
2d670 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2d680 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
2d690 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
2d6a0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2d6b0 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
2d6c0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2d6d0 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
2d6e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d6f0 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
2d700 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
2d710 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
2d720 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
2d730 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
2d740 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
2d750 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
2d760 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d770 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
2d780 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
2d790 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2d7a0 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
2d7b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2d7c0 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2d7d0 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
2d7e0 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
2d7f0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68   pointer..** ^Th
2d800 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2d810 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2d820 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65  returns 0 if the
2d830 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2d840 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2d850 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20  ep](P) returned 
2d860 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2d870 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2d880 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69  a_count(P).** wi
2d890 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65  ll return non-ze
2d8a0 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63  ro if previous c
2d8b0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2d8c0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2d8d0 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57  d.** [SQLITE_ROW
2d8e0 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65  ], except in the
2d8f0 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52   case of the [PR
2d900 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c  AGMA incremental
2d910 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72  _vacuum].** wher
2d920 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  e it always retu
2d930 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65  rns zero since e
2d940 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74  ach step of that
2d950 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70   multi-step.** p
2d960 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20  ragma returns 0 
2d970 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e  columns of data.
2d980 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2d990 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2d9a0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
2d9b0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2d9c0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2d9d0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2d9e0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
2d9f0 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
2da00 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
2da10 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
2da20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
2da30 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
2da40 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
2da50 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
2da60 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2da70 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
2da80 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
2da90 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
2daa0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2dab0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
2dac0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
2dad0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
2dae0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
2daf0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
2db00 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
2db10 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
2db20 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
2db30 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
2db40 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
2db50 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
2db60 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
2db70 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
2db80 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
2db90 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
2dba0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
2dbb0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
2dbc0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
2dbd0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
2dbe0 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
2dbf0 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
2dc00 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
2dc10 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
2dc20 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
2dc30 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
2dc40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
2dc50 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
2dc60 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
2dc70 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
2dc80 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
2dc90 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
2dca0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2dcb0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
2dcc0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
2dcd0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
2dce0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2dcf0 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
2dd00 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
2dd10 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
2dd20 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
2dd30 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2dd40 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
2dd50 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
2dd60 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
2dd70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2dd80 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2dd90 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
2dda0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
2ddb0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
2ddc0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
2ddd0 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
2dde0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2ddf0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
2de00 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
2de10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2de20 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
2de30 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
2de40 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
2de50 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
2de60 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
2de70 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
2de80 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
2de90 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
2dea0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2deb0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2dec0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
2ded0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
2dee0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
2def0 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
2df00 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
2df10 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
2df20 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
2df30 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
2df40 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2df50 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
2df60 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
2df70 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2df80 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
2df90 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
2dfa0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2dfb0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
2dfc0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
2dfd0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
2dfe0 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
2dff0 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
2e000 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2e010 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
2e020 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
2e030 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
2e040 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2e050 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2e060 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2e070 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2e080 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
2e090 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2e0a0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
2e0b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
2e0c0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
2e0d0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
2e0e0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
2e0f0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2e100 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
2e110 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2e120 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2e130 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
2e140 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2e150 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
2e160 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
2e170 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2e180 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
2e190 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2e1a0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
2e1b0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2e1c0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2e1d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e1e0 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
2e1f0 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
2e200 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
2e210 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2e220 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
2e230 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
2e240 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2e250 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2e260 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e270 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
2e280 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
2e290 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2e2a0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
2e2b0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
2e2c0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
2e2d0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
2e2e0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2e2f0 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
2e300 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2e310 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
2e320 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
2e330 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
2e340 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
2e350 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
2e360 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2e370 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2e380 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
2e390 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
2e3a0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
2e3b0 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
2e3c0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
2e3d0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
2e3e0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
2e3f0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
2e400 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2e410 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2e420 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
2e430 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
2e440 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
2e450 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
2e460 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
2e470 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
2e480 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
2e490 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
2e4a0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2e4b0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2e4c0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
2e4d0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2e4e0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
2e4f0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2e500 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2e510 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2e520 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2e530 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2e540 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
2e550 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2e560 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
2e570 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2e580 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
2e590 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2e5a0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2e5b0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2e5c0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2e5d0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2e5e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2e5f0 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2e600 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2e610 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2e620 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
2e630 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2e640 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2e650 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2e660 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2e670 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2e680 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2e690 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2e6a0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2e6b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2e6c0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2e6d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
2e6e0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2e6f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
2e700 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2e710 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2e720 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2e730 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2e740 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2e750 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
2e760 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2e770 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2e780 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2e790 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2e7a0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
2e7b0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2e7c0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2e7d0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2e7e0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2e7f0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2e800 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
2e810 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2e820 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2e830 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2e840 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
2e850 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2e860 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2e870 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2e880 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2e890 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2e8a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2e8b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
2e8c0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2e8d0 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
2e8e0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2e8f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e900 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
2e910 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e920 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
2e930 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
2e940 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
2e950 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
2e960 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
2e970 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
2e980 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2e990 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e9a0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
2e9b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e9c0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
2e9d0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
2e9e0 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
2e9f0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2ea00 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
2ea10 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
2ea20 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2ea30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2ea40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2ea50 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
2ea60 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
2ea70 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
2ea80 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
2ea90 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
2eaa0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
2eab0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2eac0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
2ead0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
2eae0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2eaf0 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  * ^The object re
2eb00 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2eb10 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2eb20 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
2eb30 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2eb40 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
2eb50 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
2eb60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2eb70 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
2eb80 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
2eb90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2eba0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2ebb0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2ebc0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
2ebd0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ebe0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2ebf0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2ec00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2ec10 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
2ec20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
2ec30 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
2ec40 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
2ec50 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
2ec60 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
2ec70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2ec80 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
2ec90 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2eca0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
2ecb0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2ecc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
2ecd0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
2ece0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
2ecf0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
2ed00 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
2ed10 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
2ed20 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
2ed30 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
2ed40 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
2ed50 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
2ed60 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
2ed70 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
2ed80 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
2ed90 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
2eda0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
2edb0 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
2edc0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
2edd0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
2ede0 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
2edf0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
2ee00 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2ee10 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
2ee20 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
2ee30 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
2ee40 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
2ee50 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
2ee60 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
2ee70 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2ee80 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2ee90 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2eea0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
2eeb0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
2eec0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
2eed0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
2eee0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2eef0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2ef00 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
2ef10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2ef20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2ef30 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2ef40 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2ef50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2ef60 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2ef70 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
2ef80 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2ef90 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
2efa0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2efb0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2efc0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2efd0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2efe0 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
2eff0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2f000 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
2f010 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
2f020 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
2f030 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2f040 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2f050 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2f060 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
2f070 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2f080 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2f090 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2f0a0 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
2f0b0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2f0c0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2f0d0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2f0e0 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64   BLOB.** <tr><td
2f0f0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2f100 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
2f110 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
2f120 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2f130 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
2f140 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
2f150 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
2f160 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2f170 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2f180 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
2f190 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2f1a0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2f1b0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
2f1c0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
2f1d0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2f1e0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2f1f0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
2f200 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2f210 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2f220 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
2f230 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
2f240 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
2f250 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
2f260 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
2f270 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
2f280 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
2f290 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
2f2a0 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
2f2b0 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
2f2c0 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
2f2d0 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
2f2e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
2f2f0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
2f300 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
2f310 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
2f320 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
2f330 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
2f340 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
2f350 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
2f360 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
2f370 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
2f380 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
2f390 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
2f3a0 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
2f3b0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
2f3c0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
2f3d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
2f3e0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
2f3f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2f400 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
2f410 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
2f420 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
2f430 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
2f440 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
2f450 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
2f460 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
2f470 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
2f480 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
2f490 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
2f4a0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
2f4b0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
2f4c0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2f4d0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
2f4e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f4f0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2f500 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f510 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2f520 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
2f530 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
2f540 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
2f550 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
2f560 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
2f570 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2f580 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
2f590 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2f5a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
2f5b0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2f5c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2f5d0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
2f5e0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
2f5f0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
2f600 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
2f610 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
2f620 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2f630 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
2f640 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2f650 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
2f660 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2f670 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
2f680 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2f690 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2f6a0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2f6b0 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
2f6c0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
2f6d0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
2f6e0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
2f6f0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
2f700 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
2f710 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
2f720 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
2f730 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
2f740 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
2f750 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
2f760 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
2f770 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
2f780 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
2f790 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
2f7a0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
2f7b0 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
2f7c0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
2f7d0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
2f7e0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
2f7f0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
2f800 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
2f810 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
2f820 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
2f830 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
2f840 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
2f850 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
2f860 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
2f870 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
2f880 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
2f890 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
2f8a0 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
2f8b0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
2f8c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f8d0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
2f8e0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2f8f0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
2f900 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2f910 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
2f920 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2f930 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2f940 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2f950 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2f960 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
2f970 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f980 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
2f990 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2f9a0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
2f9b0 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
2f9c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f9d0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
2f9e0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
2f9f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fa00 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
2fa10 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
2fa20 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
2fa30 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
2fa40 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
2fa50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2fa60 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2fa70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2fa80 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
2fa90 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
2faa0 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
2fab0 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
2fac0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
2fad0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2fae0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
2faf0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2fb00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2fb10 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
2fb20 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
2fb30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2fb40 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
2fb50 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2fb60 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
2fb70 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
2fb80 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
2fb90 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
2fba0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
2fbb0 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
2fbc0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
2fbd0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
2fbe0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2fbf0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2fc00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2fc10 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
2fc20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
2fc30 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
2fc40 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
2fc50 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
2fc60 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
2fc70 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
2fc80 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
2fc90 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
2fca0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2fcb0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
2fcc0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
2fcd0 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
2fce0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
2fcf0 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
2fd00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2fd10 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
2fd20 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
2fd30 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
2fd40 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
2fd50 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
2fd60 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
2fd70 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
2fd80 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
2fd90 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
2fda0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2fdb0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
2fdc0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
2fdd0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2fde0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
2fdf0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
2fe00 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
2fe10 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
2fe20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2fe30 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
2fe40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2fe50 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2fe60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
2fe70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2fe80 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2fe90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2fea0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2feb0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
2fec0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
2fed0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
2fee0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2fef0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2ff00 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
2ff10 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2ff20 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
2ff30 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
2ff40 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
2ff50 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2ff60 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
2ff70 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2ff80 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
2ff90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2ffa0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
2ffb0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ffc0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2ffd0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2ffe0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2fff0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
30000 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
30010 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
30020 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
30030 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
30040 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30050 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30060 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
30070 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
30080 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
30090 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
300a0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
300b0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
300c0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
300d0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
300e0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
300f0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
30100 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
30110 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
30120 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
30130 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
30140 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
30150 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
30160 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
30170 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
30180 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
30190 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
301a0 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
301b0 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
301c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
301d0 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
301e0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
301f0 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
30200 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
30210 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
30220 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30230 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
30240 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
30250 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
30260 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
30270 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
30280 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
30290 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
302a0 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
302b0 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
302c0 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
302d0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
302e0 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
302f0 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
30300 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
30310 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
30320 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
30330 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
30340 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
30350 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
30360 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
30370 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
30380 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
30390 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
303a0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
303b0 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
303c0 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
303d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
303e0 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
303f0 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
30400 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
30410 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
30420 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
30430 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
30440 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
30450 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
30460 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
30470 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
30480 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
30490 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
304a0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
304b0 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
304c0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
304d0 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
304e0 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
304f0 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
30500 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
30510 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
30520 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
30530 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
30540 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
30550 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
30560 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
30570 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
30580 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
30590 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
305a0 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
305b0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
305c0 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
305d0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
305e0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
305f0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
30600 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
30610 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
30620 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
30630 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
30640 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
30650 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
30660 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
30670 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
30680 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
30690 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
306a0 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
306b0 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
306c0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
306d0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
306e0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
306f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30700 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
30710 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
30720 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
30730 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
30740 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
30750 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
30760 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
30770 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30780 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
30790 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
307a0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
307b0 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
307c0 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
307d0 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
307e0 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
307f0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
30800 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
30810 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
30820 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
30830 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
30840 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
30850 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
30860 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30870 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
30880 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
30890 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
308a0 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
308b0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
308c0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
308d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
308e0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
308f0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
30900 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
30910 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
30920 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
30930 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
30940 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
30950 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
30960 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
30970 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
30980 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
30990 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
309a0 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
309b0 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
309c0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
309d0 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
309e0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
309f0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
30a00 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
30a10 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
30a20 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
30a30 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
30a40 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
30a50 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
30a60 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
30a70 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
30a80 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
30a90 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
30aa0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
30ab0 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
30ac0 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
30ad0 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
30ae0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
30af0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
30b00 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
30b10 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
30b20 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
30b30 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
30b40 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
30b50 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
30b60 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
30b70 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
30b80 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
30b90 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
30ba0 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
30bb0 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
30bc0 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
30bd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
30be0 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
30bf0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
30c00 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
30c10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30c20 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
30c30 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
30c40 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
30c50 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
30c60 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
30c70 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
30c80 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
30c90 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
30ca0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
30cb0 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
30cc0 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
30cd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30ce0 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
30cf0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
30d00 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
30d10 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
30d20 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30d30 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
30d40 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
30d50 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
30d60 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
30d70 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
30d80 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
30d90 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
30da0 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
30db0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
30dc0 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
30dd0 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
30de0 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
30df0 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
30e00 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
30e10 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
30e20 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
30e30 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
30e40 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
30e50 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
30e60 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
30e70 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
30e80 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
30e90 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
30ea0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
30eb0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
30ec0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
30ed0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
30ee0 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
30ef0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
30f00 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
30f10 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
30f20 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
30f30 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
30f40 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
30f50 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
30f60 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
30f70 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
30f80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
30f90 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
30fa0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
30fb0 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
30fc0 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
30fd0 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
30fe0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
30ff0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
31000 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
31010 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
31020 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
31030 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
31040 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
31050 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
31060 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
31070 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
31080 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c  eters.  The appl
31090 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73  ication should s
310a0 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  et this paramete
310b0 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r to.** [SQLITE_
310c0 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20  UTF16LE] if the 
310d0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
310e0 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  ntation invokes 
310f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
31100 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f  ue_text16le()] o
31110 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b  n an input, or [
31120 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20  SQLITE_UTF16BE] 
31130 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  if the.** implem
31140 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
31150 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
31160 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61  text16be()] on a
31170 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b  n input, or.** [
31180 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66  SQLITE_UTF16] if
31190 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
311a0 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65  text16()] is use
311b0 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  d, or [SQLITE_UT
311c0 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  F8].** otherwise
311d0 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c  .  ^The same SQL
311e0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
311f0 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
31200 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67  iple times using
31210 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72  .** different pr
31220 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
31230 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66  odings, with dif
31240 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  ferent implement
31250 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61  ations for.** ea
31260 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20  ch encoding..** 
31270 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
31280 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
31290 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
312a0 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
312b0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
312c0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
312d0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
312e0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
312f0 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
31300 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
31310 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61  rth parameter ma
31320 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20  y optionally be 
31330 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  ORed with [SQLIT
31340 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d  E_DETERMINISTIC]
31350 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68  .** to signal th
31360 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  at the function 
31370 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
31380 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75  rn the same resu
31390 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20  lt given.** the 
313a0 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68  same inputs with
313b0 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  in a single SQL 
313c0 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74  statement.  Most
313d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
313e0 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73  re.** determinis
313f0 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d  tic.  The built-
31400 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51  in [random()] SQ
31410 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e  L function is an
31420 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a   example of a.**
31430 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69   function that i
31440 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73  s not determinis
31450 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65  tic.  The SQLite
31460 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69   query planner i
31470 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72  s able to.** per
31480 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20  form additional 
31490 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e  optimizations on
314a0 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66   deterministic f
314b0 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65  unctions, so use
314c0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
314d0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
314e0 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d  ] flag is recomm
314f0 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73  ended where poss
31500 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ible..**.** ^(Th
31510 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
31520 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
31530 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
31540 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
31550 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
31560 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
31570 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
31580 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
31590 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
315a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
315b0 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65  h, seventh and e
315c0 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73  ighth parameters
315d0 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
315e0 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
315f0 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
31600 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
31610 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
31620 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
31630 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
31640 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
31650 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
31660 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
31670 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
31680 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
31690 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
316a0 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  rs must be passe
316b0 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
316c0 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
316d0 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
316e0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
316f0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
31700 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
31710 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
31720 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70  Final and NULL p
31730 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70  ointer must be p
31740 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
31750 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
31760 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
31770 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
31780 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
31790 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c  pointers for all
317a0 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
317b0 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
317c0 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e  .** ^(If the nin
317d0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
317e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
317f0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
31800 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
31810 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
31820 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
31830 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
31840 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
31850 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
31860 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
31870 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
31880 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
31890 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
318a0 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
318b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
318c0 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
318d0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
318e0 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
318f0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
31900 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31910 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
31920 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
31930 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
31940 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
31950 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
31960 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
31970 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
31980 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
31990 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
319a0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
319b0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
319c0 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
319d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
319e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
319f0 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
31a00 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
31a10 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
31a20 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
31a30 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
31a40 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
31a50 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
31a60 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
31a70 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
31a80 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
31a90 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
31aa0 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
31ab0 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
31ac0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
31ad0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
31ae0 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
31af0 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
31b00 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
31b10 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
31b20 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
31b30 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
31b40 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
31b50 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
31b60 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
31b70 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
31b80 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
31b90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
31ba0 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
31bb0 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63  e nArg.  ^A func
31bc0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
31bd0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
31be0 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
31bf0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
31c00 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
31c10 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
31c20 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
31c30 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
31c40 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
31c50 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  ** ^A function w
31c60 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
31c70 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
31c80 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
31c90 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
31ca0 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
31cb0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
31cc0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
31cd0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
31ce0 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
31cf0 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
31d00 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e  ** ^Built-in fun
31d10 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
31d20 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
31d30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31d40 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
31d50 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
31d60 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31d70 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
31d80 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
31d90 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
31da0 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
31db0 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
31dc0 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
31dd0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
31de0 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
31df0 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
31e00 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
31e10 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
31e20 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
31e30 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
31e40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31e50 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
31e60 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
31e70 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
31e80 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
31e90 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
31ea0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
31eb0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
31ec0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
31ed0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
31ee0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
31ef0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
31f00 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
31f10 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
31f20 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
31f30 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
31f40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
31f50 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
31f60 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
31f70 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
31f80 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
31f90 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
31fa0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
31fb0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
31fc0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
31fd0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
31fe0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
31ff0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
32000 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
32010 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
32020 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
32030 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
32040 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
32050 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32060 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  nction_v2(.  sql
32070 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
32080 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
32090 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
320a0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
320b0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
320c0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
320d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
320e0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
320f0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
32100 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
32110 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
32120 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
32130 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
32140 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32150 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
32160 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a  roy)(void*).);..
32170 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32180 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
32190 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
321a0 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
321b0 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
321c0 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
321d0 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
321e0 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
321f0 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
32200 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
32210 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20  8           1   
32220 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34   /* IMP: R-37514
32230 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e  -35566 */.#defin
32240 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
32250 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20          2    /* 
32260 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36  IMP: R-03371-376
32270 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  37 */.#define SQ
32280 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
32290 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a      3    /* IMP:
322a0 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a   R-51971-34154 *
322b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
322c0 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
322d0 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
322e0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
322f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
32300 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
32310 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65      /* Deprecate
32320 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
32330 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
32340 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
32350 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32360 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
32370 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
32380 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a  ction Flags.**.*
32390 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
323a0 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f  s may be ORed to
323b0 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20  gether with the 
323c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
323d0 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78   | preferred tex
323e0 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74  t encoding] as t
323f0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
32400 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  nt.** to [sqlite
32410 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
32420 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
32430 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
32440 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
32450 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32460 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64  ion_v2()]..*/.#d
32470 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
32480 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78  ERMINISTIC    0x
32490 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
324a0 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
324b0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
324c0 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
324d0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
324e0 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
324f0 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
32500 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
32510 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
32520 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
32530 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
32540 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
32550 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
32560 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
32570 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
32580 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
32590 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
325a0 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
325b0 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
325c0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
325d0 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
325e0 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
325f0 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
32600 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
32610 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
32620 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
32630 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
32640 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
32650 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
32660 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32670 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
32680 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
32690 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
326a0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
326b0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
326c0 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
326d0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
326e0 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
326f0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
32700 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
32710 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
32720 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
32730 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
32740 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
32750 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
32760 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
32770 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
32780 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
32790 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
327a0 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20  _int64,int),.   
327b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
327c0 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33     void*,sqlite3
327d0 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
327e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
327f0 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
32800 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
32810 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
32820 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
32830 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
32840 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
32850 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
32860 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
32870 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
32880 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
32890 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
328a0 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
328b0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
328c0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
328d0 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
328e0 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
328f0 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
32900 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
32910 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
32920 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
32930 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
32940 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
32950 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
32960 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
32970 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
32980 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
32990 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
329a0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
329b0 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
329c0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
329d0 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
329e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
329f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
32a00 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
32a10 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
32a20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
32a30 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
32a40 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
32a50 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
32a60 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
32a70 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
32a80 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
32a90 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
32aa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
32ab0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
32ac0 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
32ad0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
32ae0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
32af0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
32b00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
32b10 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
32b20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
32b30 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
32b40 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
32b50 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
32b60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
32b70 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
32b80 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
32b90 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
32ba0 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
32bb0 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72  ept that these r
32bc0 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
32bd0 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
32be0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
32bf0 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
32c00 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
32c10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
32c20 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
32c30 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
32c40 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
32c50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32c60 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
32c70 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
32c80 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
32c90 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
32ca0 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
32cb0 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
32cc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
32cd0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
32ce0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
32cf0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
32d00 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
32d10 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
32d20 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
32d30 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
32d40 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
32d50 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
32d60 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
32d70 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
32d80 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
32d90 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
32da0 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
32db0 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
32dc0 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
32dd0 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
32de0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
32df0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
32e00 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
32e10 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
32e20 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
32e30 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
32e40 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
32e50 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
32e60 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
32e70 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
32e80 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
32e90 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
32ea0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
32eb0 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
32ec0 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
32ed0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
32ee0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
32ef0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
32f00 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
32f10 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
32f20 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
32f30 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
32f40 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
32f50 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
32f60 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
32f70 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
32f80 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
32f90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32fa0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
32fb0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
32fc0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
32fd0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
32fe0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
32ff0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
33000 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
33010 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
33020 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
33030 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
33040 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
33050 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
33060 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
33070 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
33080 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
33090 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
330a0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
330b0 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
330c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
330d0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
330e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
330f0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
33100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33110 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
33120 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
33130 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
33140 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
33150 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
33160 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  e*);.double sqli
33170 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
33180 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33190 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
331a0 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
331b0 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33  value*);.sqlite3
331c0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
331d0 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
331e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
331f0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
33200 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
33210 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
33220 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
33230 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
33240 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
33250 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
33260 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
33270 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
33280 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
33290 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
332a0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
332b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
332c0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
332d0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
332e0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
332f0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
33300 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
33310 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
33320 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
33330 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
33340 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  n Context.**.** 
33350 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
33360 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
33370 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
33380 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
33390 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
333a0 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
333b0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
333c0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
333d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
333e0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
333f0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
33400 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
33410 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
33420 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
33430 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
33440 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
33450 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
33460 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
33470 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
33480 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
33490 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
334a0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
334b0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
334c0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
334d0 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
334e0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
334f0 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
33500 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
33510 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
33520 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
33530 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
33540 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
33550 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
33560 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
33570 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
33580 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
33590 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
335a0 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
335b0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
335c0 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
335d0 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
335e0 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
335f0 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
33600 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
33610 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
33620 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
33630 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
33640 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
33650 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
33660 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
33670 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
33680 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33690 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
336a0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
336b0 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
336c0 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
336d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
336e0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
336f0 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
33700 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
33710 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68  L pointer .** wh
33720 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20  en first called 
33730 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  if N is less tha
33740 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
33750 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  ro or if a memor
33760 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72  y.** allocate er
33770 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
33780 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
33790 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
337a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
337b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
337c0 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
337d0 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
337e0 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
337f0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
33800 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
33810 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
33820 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
33830 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
33840 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
33850 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
33860 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
33870 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
33880 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
33890 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
338a0 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68  ocation.)^  With
338b0 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  in the xFinal ca
338c0 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75  llback, it is cu
338d0 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a  stomary to set.*
338e0 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74  * N=0 in calls t
338f0 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
33900 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
33910 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20   so that no .** 
33920 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79  pointless memory
33930 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63   allocations occ
33940 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ur..**.** ^SQLit
33950 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
33960 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
33970 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
33980 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
33990 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
339a0 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
339b0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
339c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
339d0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
339e0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
339f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
33a00 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
33a10 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
33a20 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
33a30 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
33a40 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
33a50 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
33a60 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
33a70 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
33a80 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
33a90 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
33aa0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
33ab0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
33ac0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
33ad0 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
33ae0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
33af0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
33b00 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
33b10 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
33b20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
33b30 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
33b40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
33b50 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
33b60 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
33b70 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
33b80 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
33b90 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
33ba0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
33bb0 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
33bc0 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
33bd0 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
33be0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
33bf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33c00 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
33c10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33c20 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
33c30 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
33c40 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
33c50 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
33c60 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
33c70 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
33c80 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
33c90 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
33ca0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
33cb0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
33cc0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33cd0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
33ce0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
33cf0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
33d00 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
33d10 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
33d20 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
33d30 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
33d40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
33d50 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
33d60 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
33d70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
33d80 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
33d90 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
33da0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
33db0 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
33dc0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
33dd0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
33de0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
33df0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
33e00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33e10 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
33e20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
33e30 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
33e40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
33e50 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
33e60 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
33e70 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
33e80 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
33e90 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
33ea0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
33eb0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
33ec0 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  a.**.** These fu
33ed0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
33ee0 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72  sed by (non-aggr
33ef0 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74  egate) SQL funct
33f00 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
33f10 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
33f20 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
33f30 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
33f40 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
33f50 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
33f60 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
33f70 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
33f80 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
33f90 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
33fa0 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
33fb0 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
33fc0 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
33fd0 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
33fe0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a  .  An example.**
33ff0 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d   of where this m
34000 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69  ight be useful i
34010 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65  s in a regular-e
34020 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
34030 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ng.** function. 
34040 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
34050 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
34060 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
34070 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a  an be stored as.
34080 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  ** metadata asso
34090 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
340a0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20  pattern string. 
340b0 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e   .** Then as lon
340c0 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e  g as the pattern
340d0 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20   string remains 
340e0 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65  the same,.** the
340f0 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
34100 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
34110 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
34120 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
34130 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
34140 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  e function..**.*
34150 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
34160 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
34170 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
34180 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
34190 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
341a0 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
341b0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
341c0 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
341d0 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
341e0 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
341f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
34200 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
34210 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f   ^If there is no
34220 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
34230 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
34240 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
34250 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33  nt, this sqlite3
34260 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
34270 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
34280 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
34290 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
342a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
342b0 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65  ta(C,N,P,X) inte
342c0 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73  rface saves P as
342d0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
342e0 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
342f0 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
34300 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34310 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71  nction.  ^Subseq
34320 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
34330 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
34340 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e  data(C,N) return
34350 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74   P from the most
34360 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74   recent.** sqlit
34370 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
34380 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20  ,N,P,X) call if 
34390 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
343a0 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a  still valid or.*
343b0 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65  * NULL if the me
343c0 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
343d0 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41  discarded..** ^A
343e0 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74  fter each call t
343f0 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
34400 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77  xdata(C,N,P,X) w
34410 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55  here X is not NU
34420 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  LL,.** SQLite wi
34430 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
34440 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
34450 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74  n X with paramet
34460 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20  er P exactly.** 
34470 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d  once, when the m
34480 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61  etadata is disca
34490 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  rded..** SQLite 
344a0 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61  is free to disca
344b0 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  rd the metadata 
344c0 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63  at any time, inc
344d0 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20  luding: <ul>.** 
344e0 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f  <li> when the co
344f0 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
34500 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
34510 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c  hanges, or.** <l
34520 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  i> when [sqlite3
34530 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
34540 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
34550 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20  ] is called for 
34560 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20  the.**      SQL 
34570 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a  statement, or.**
34580 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74   <li> when sqlit
34590 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
345a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69   is invoked agai
345b0 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61  n on the same pa
345c0 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c  rameter, or.** <
345d0 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f  li> during the o
345e0 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f  riginal sqlite3_
345f0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61  set_auxdata() ca
34600 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79  ll when a memory
34610 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61   .**      alloca
34620 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
34630 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  s. </ul>)^.**.**
34640 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62   Note the last b
34650 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75  ullet in particu
34660 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75  lar.  The destru
34670 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71  ctor X in .** sq
34680 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
34690 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74  a(C,N,P,X) might
346a0 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64   be called immed
346b0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74  iately, before t
346c0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  he.** sqlite3_se
346d0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
346e0 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72  rface even retur
346f0 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74  ns.  Hence sqlit
34700 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
34710 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61  .** should be ca
34720 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e  lled near the en
34730 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  d of the functio
34740 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
34750 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63   and the.** func
34760 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
34770 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d  ion should not m
34780 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50  ake any use of P
34790 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65   after.** sqlite
347a0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
347b0 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e  has been called.
347c0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63  .**.** ^(In prac
347d0 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
347e0 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
347f0 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
34800 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ls for.** functi
34810 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  on parameters th
34820 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74  at are compile-t
34830 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69  ime constants, i
34840 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c  ncluding literal
34850 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b  .** values and [
34860 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20  parameters] and 
34870 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70  expressions comp
34880 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  osed from the sa
34890 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  me.)^.**.** Thes
348a0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
348b0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
348c0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
348d0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
348e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
348f0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
34900 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
34910 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
34920 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76  text*, int N);.v
34930 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
34940 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
34950 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
34960 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
34970 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
34980 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
34990 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
349a0 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
349b0 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
349c0 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
349d0 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
349e0 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
349f0 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
34a00 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
34a10 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
34a20 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
34a30 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
34a40 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72  .  ^If the destr
34a50 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
34a60 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
34a70 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
34a80 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
34a90 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
34aa0 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
34ab0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
34ac0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
34ad0 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
34ae0 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  ^The.** SQLITE_T
34af0 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
34b00 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
34b10 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
34b20 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
34b30 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
34b40 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
34b50 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
34b60 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
34b70 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
34b80 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
34b90 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
34ba0 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
34bb0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
34bc0 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
34bd0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
34be0 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64  pilers..*/.typed
34bf0 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
34c00 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
34c10 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
34c20 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
34c30 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
34c40 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
34c50 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
34c60 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
34c70 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
34c80 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
34c90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
34ca0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
34cb0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
34cc0 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
34cd0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
34ce0 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
34cf0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
34d00 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
34d10 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
34d20 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
34d30 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
34d40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34d50 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
34d60 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34d70 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
34d80 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
34d90 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
34da0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
34db0 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
34dc0 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
34dd0 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
34de0 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
34df0 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
34e00 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
34e10 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
34e20 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
34e30 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
34e40 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
34e50 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
34e60 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
34e70 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
34e80 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34e90 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
34ea0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
34eb0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
34ec0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34ed0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
34ee0 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
34ef0 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
34f00 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
34f10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
34f20 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
34f30 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
34f40 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
34f50 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
34f60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34f70 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
34f80 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
34f90 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
34fa0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
34fb0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34fc0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
34fd0 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
34fe0 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
34ff0 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
35000 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
35010 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
35020 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
35030 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35040 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
35050 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
35060 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
35070 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
35080 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35090 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
350a0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
350b0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
350c0 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
350d0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
350e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
350f0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
35100 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
35110 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
35120 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
35130 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
35140 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
35150 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
35160 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
35170 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
35180 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
35190 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
351a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
351b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
351c0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
351d0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
351e0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
351f0 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
35200 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
35210 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
35220 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
35230 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
35240 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
35250 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
35260 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
35270 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35280 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
35290 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
352a0 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
352b0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
352c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
352d0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
352e0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
352f0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
35300 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
35310 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
35320 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
35330 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
35340 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
35350 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
35360 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
35370 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
35380 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35390 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
353a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
353b0 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
353c0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
353d0 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
353e0 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
353f0 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
35400 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
35410 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
35420 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
35430 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35440 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
35450 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
35460 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
35470 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
35480 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
35490 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
354a0 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
354b0 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
354c0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
354d0 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
354e0 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
354f0 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
35500 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
35510 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
35520 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35530 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
35540 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
35550 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
35560 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
35570 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
35580 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
35590 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
355a0 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
355b0 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
355c0 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
355d0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
355e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
355f0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
35600 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
35610 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
35620 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
35630 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
35640 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35650 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
35660 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
35670 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
35680 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
35690 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
356a0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
356b0 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f  B is too long to
356c0 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
356d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
356e0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
356f0 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
35700 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
35710 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
35720 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
35730 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
35740 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
35750 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35760 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
35770 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
35780 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
35790 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
357a0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
357b0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
357c0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
357d0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
357e0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
357f0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
35800 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
35810 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  nt64() interface
35820 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
35830 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
35840 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35850 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
35860 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73   be the 64-bit s
35870 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
35880 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
35890 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
358a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
358b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
358c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
358d0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
358e0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
358f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35900 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
35910 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
35920 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35930 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
35940 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
35950 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
35960 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
35970 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
35980 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
35990 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
359a0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
359b0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
359c0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
359d0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
359e0 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
359f0 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
35a00 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
35a10 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
35a20 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
35a30 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
35a40 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
35a50 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
35a60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35a70 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34 28 29  _result_text64()
35a80 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
35a90 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
35aa0 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63   of an.** applic
35ab0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35ac0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 74  nction to be a t
35ad0 65 78 74 20 73 74 72 69 6e 67 20 69 6e 20 61 6e  ext string in an
35ae0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73 70 65   encoding.** spe
35af0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
35b00 66 74 68 20 28 61 6e 64 20 6c 61 73 74 29 20 70  fth (and last) p
35b10 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20  arameter, which 
35b20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a 20 6f  must be one.** o
35b30 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
35b40 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
35b50 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
35b60 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
35b70 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 4c 69  F16LE]..** ^SQLi
35b80 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
35b90 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
35ba0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
35bb0 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
35bc0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
35bd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35be0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
35bf0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
35c00 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
35c10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35c20 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
35c30 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
35c40 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
35c50 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
35c60 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
35c70 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
35c80 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
35c90 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
35ca0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
35cb0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
35cc0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
35cd0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
35ce0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
35cf0 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
35d00 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
35d10 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
35d20 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
35d30 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
35d40 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
35d50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35d60 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
35d70 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68  n result.  If th
35d80 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
35d90 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
35da0 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74   then it.** must
35db0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
35dc0 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72  set into the str
35dd0 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55  ing where the NU
35de0 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
35df0 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20  ld.** appear if 
35e00 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
35e10 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e   NUL terminated.
35e20 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
35e30 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a  racters occur.**
35e40 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61   in the string a
35e50 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20  t a byte offset 
35e60 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61  that is less tha
35e70 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
35e80 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65  he 3rd.** parame
35e90 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ter, then the re
35ea0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77  sulting string w
35eb0 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  ill contain embe
35ec0 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68  dded NULs and th
35ed0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65  e.** result of e
35ee0 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61  xpressions opera
35ef0 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20  ting on strings 
35f00 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
35f10 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
35f20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
35f30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
35f40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35f50 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
35f60 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
35f70 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
35f80 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
35f90 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
35fa0 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
35fb0 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
35fc0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
35fd0 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
35fe0 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
35ff0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
36000 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
36010 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
36020 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
36030 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36040 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20  * interfaces or 
36050 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  to.** sqlite3_re
36060 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
36070 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
36080 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
36090 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
360a0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
360b0 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
360c0 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
360d0 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
360e0 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
360f0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
36100 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20  e parameter nor 
36110 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
36120 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74  r on the content
36130 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20  .** when it has 
36140 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
36150 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
36160 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
36170 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
36180 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
36190 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
361a0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
361b0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
361c0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
361d0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
361e0 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
361f0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
36200 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
36210 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
36220 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
36230 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
36240 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
36250 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36260 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
36270 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
36280 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
36290 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
362a0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
362b0 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
362c0 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
362d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
362e0 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
362f0 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
36300 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a  arameter.  ^The.
36310 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
36320 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
36330 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
36340 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
36350 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
36360 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
36370 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
36380 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
36390 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
363a0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
363b0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
363c0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
363d0 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
363e0 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74  arm..** ^A [prot
363f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
36400 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
36410 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
36420 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
36430 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
36440 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
36450 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
36460 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
36470 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
36480 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
36490 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
364a0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
364b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
364c0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
364d0 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
364e0 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
364f0 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
36500 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
36510 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36520 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
36530 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
36540 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
36550 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
36560 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
36570 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
36580 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
36590 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
365a0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
365b0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
365c0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
365d0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 36 34 28 73  _result_blob64(s
365e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
365f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 0a 20 20 20  const void*,.   
36600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36610 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
36620 75 69 6e 74 36 34 2c 76 6f 69 64 28 2a 29 28 76  uint64,void(*)(v
36630 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
36640 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
36650 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
36660 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
36670 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36680 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
36690 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
366a0 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
366b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
366c0 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
366d0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
366e0 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
366f0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36700 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
36710 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
36720 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36730 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
36740 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
36750 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
36760 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
36770 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
36780 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
36790 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
367a0 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
367b0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
367c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
367d0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
367e0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
367f0 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
36800 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
36810 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36820 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
36830 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
36840 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
36850 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
36860 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
36870 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36880 65 73 75 6c 74 5f 74 65 78 74 36 34 28 73 71 6c  esult_text64(sql
36890 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
368a0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
368b0 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
368c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
368d0 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
368e0 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63  id*), unsigned c
368f0 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 76  har encoding);.v
36900 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36910 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
36920 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
36930 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
36940 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
36950 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36960 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
36970 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
36980 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
36990 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
369a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
369b0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
369c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
369d0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
369e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
369f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36a00 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
36a10 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
36a20 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
36a30 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36a40 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
36a50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
36a60 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
36a70 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
36a80 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
36a90 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  nces.**.** ^Thes
36aa0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
36ab0 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
36ac0 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
36ad0 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
36ae0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
36af0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
36b00 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
36b10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
36b20 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
36b30 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
36b40 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
36b50 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
36b60 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36b70 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
36b80 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36b90 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
36ba0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
36bb0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
36bc0 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
36bd0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
36be0 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
36bf0 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
36c00 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
36c10 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
36c20 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
36c30 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
36c40 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
36c50 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
36c60 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
36c70 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
36c80 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
36c90 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
36ca0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
36cb0 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
36cc0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
36cd0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
36ce0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
36cf0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
36d00 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
36d10 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
36d20 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
36d30 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
36d40 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
36d50 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
36d60 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
36d70 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
36d80 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36d90 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
36da0 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
36db0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
36dc0 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
36dd0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
36de0 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
36df0 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
36e00 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
36e10 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
36e20 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
36e30 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
36e40 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
36e50 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
36e60 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
36e70 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
36e80 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
36e90 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
36ea0 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20  nt, pArg, is an 
36eb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
36ec0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
36ed0 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75   passed.** throu
36ee0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
36ef0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
36f00 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36f10 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
36f20 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
36f30 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63  gument, xCallbac
36f40 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  k, is a pointer 
36f50 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
36f60 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d   function..** ^M
36f70 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e  ultiple collatin
36f80 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  g functions can 
36f90 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73  be registered us
36fa0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
36fb0 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69  e but.** with di
36fc0 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
36fd0 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
36fe0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
36ff0 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e  whichever.** fun
37000 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74  ction requires t
37010 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
37020 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72  of data transfor
37030 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  mation..** ^If t
37040 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67  he xCallback arg
37050 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68  ument is NULL th
37060 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  en the collating
37070 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
37080 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20  deleted.  ^When 
37090 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  all collating fu
370a0 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74  nctions having t
370b0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  he same name are
370c0 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61   deleted,.** tha
370d0 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e  t collation is n
370e0 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e  o longer usable.
370f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c  .**.** ^The coll
37100 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
37110 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
37120 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f  ed with a copy o
37130 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61  f the pArg .** a
37140 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
37150 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68  pointer and with
37160 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20   two strings in 
37170 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
37180 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
37190 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
371a0 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69  nt.  The collati
371b0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
371c0 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e   return an.** in
371d0 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65  teger that is ne
371e0 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72  gative, zero, or
371f0 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20   positive.** if 
37200 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
37210 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65   is less than, e
37220 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
37230 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
37240 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ond,.** respecti
37250 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69  vely.  A collati
37260 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
37270 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
37280 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a  he same answer.*
37290 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65  * given the same
372a0 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f   inputs.  If two
372b0 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69   or more collati
372c0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
372d0 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74   registered.** t
372e0 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61  o the same colla
372f0 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67  tion name (using
37300 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
37310 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e  Rep values) then
37320 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76   all.** must giv
37330 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20  e an equivalent 
37340 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f  answer when invo
37350 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c  ked with equival
37360 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  ent strings..** 
37370 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
37380 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79  nction must obey
37390 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70   the following p
373a0 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c  roperties for al
373b0 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20  l.** strings A, 
373c0 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20  B, and C:.**.** 
373d0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  <ol>.** <li> If 
373e0 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a  A==B then B==A..
373f0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
37400 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d  and B==C then A=
37410 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =C..** <li> If A
37420 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b  &lt;B THEN B&gt;
37430 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  A..** <li> If A&
37440 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20  lt;B and B&lt;C 
37450 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20  then A&lt;C..** 
37460 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  </ol>.**.** If a
37470 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37480 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66  ion fails any of
37490 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74   the above const
374a0 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a  raints and that.
374b0 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ** collating fun
374c0 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74  ction is  regist
374d0 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74  ered and used, t
374e0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
374f0 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73   of SQLite.** is
37500 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
37510 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
37520 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
37530 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
37540 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37550 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69  ollation().** wi
37560 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20  th the addition 
37570 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f  that the xDestro
37580 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  y callback is in
37590 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68  voked on pArg wh
375a0 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  en.** the collat
375b0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
375c0 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c  deleted..** ^Col
375d0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
375e0 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65   are deleted whe
375f0 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
37600 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a  idden by later.*
37610 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63  * calls to the c
37620 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
37630 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
37640 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  hen the.** [data
37650 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37660 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
37670 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
37680 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  )]..**.** ^The x
37690 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
376a0 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63   is <u>not</u> c
376b0 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a  alled if the .**
376c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
376d0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66  collation_v2() f
376e0 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  unction fails.  
376f0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
37700 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  t invoke.** sqli
37710 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37720 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61  tion_v2() with a
37730 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72   non-NULL xDestr
37740 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  oy argument shou
37750 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65  ld .** check the
37760 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64   return code and
37770 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
37780 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
37790 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d   pointer.** them
377a0 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68  selves rather th
377b0 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c  an expecting SQL
377c0 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68  ite to deal with
377d0 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a   it for them..**
377e0 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65   This is differe
377f0 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74  nt from every ot
37800 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
37810 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e  face.  The incon
37820 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20  sistency .** is 
37830 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20  unfortunate but 
37840 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
37850 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
37860 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a  ng backwards .**
37870 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
37880 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
37890 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
378a0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
378b0 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  d [sqlite3_colla
378c0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d  tion_needed16()]
378d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
378e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
378f0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
37900 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
37910 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
37920 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
37930 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
37940 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
37950 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
37960 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
37970 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
37980 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
37990 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
379a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
379b0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
379c0 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
379d0 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
379e0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
379f0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
37a00 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
37a10 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
37a20 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
37a30 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37a40 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
37a50 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
37a60 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
37a70 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
37a80 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
37a90 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
37aa0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
37ab0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
37ac0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
37ad0 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
37ae0 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a  eeded Callbacks.
37af0 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20  **.** ^To avoid 
37b00 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
37b10 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
37b20 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
37b30 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
37b40 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
37b50 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
37b60 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
37b70 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
37b80 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
37b90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
37ba0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
37bb0 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
37bc0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
37bd0 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
37be0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
37bf0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
37c00 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
37c10 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
37c20 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
37c30 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
37c40 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
37c50 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
37c60 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
37c70 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
37c80 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
37c90 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  . ^If sqlite3_co
37ca0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
37cb0 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
37cc0 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
37cd0 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
37ce0 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
37cf0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
37d00 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
37d10 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
37d20 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20  es the existing 
37d30 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64  collation-needed
37d40 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
37d50 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c   ^(When the call
37d60 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
37d70 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
37d80 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
37d90 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
37da0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
37db0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
37dc0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
37dd0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
37de0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
37df0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
37e00 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
37e10 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
37e20 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
37e30 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
37e40 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
37e50 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
37e60 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
37e70 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
37e80 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
37e90 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
37ea0 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
37eb0 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
37ec0 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
37ed0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
37ee0 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
37ef0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
37f00 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
37f10 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  quence.)^.**.** 
37f20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
37f30 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
37f40 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
37f50 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
37f60 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
37f70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
37f80 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
37f90 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
37fa0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
37fb0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37fc0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  on_v2()]..*/.int
37fd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
37fe0 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
37ff0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
38000 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
38010 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
38020 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
38030 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
38040 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
38050 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
38060 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
38070 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
38080 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
38090 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
380a0 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  .);..#ifdef SQLI
380b0 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a  TE_HAS_CODEC./*.
380c0 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b  ** Specify the k
380d0 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70  ey for an encryp
380e0 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54  ted database.  T
380f0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  his routine shou
38100 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20  ld be.** called 
38110 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69  right after sqli
38120 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a  te3_open()..**.*
38130 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
38140 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
38150 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
38160 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
38170 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
38180 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
38190 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69  ite3_key(.  sqli
381a0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
381b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
381c0 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
381d0 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
381e0 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
381f0 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
38200 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  key */.);.int sq
38210 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20  lite3_key_v2(.  
38220 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
38230 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
38240 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
38250 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
38260 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
38270 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  e,           /* 
38280 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  Name of the data
38290 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
382a0 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
382b0 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
382c0 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
382d0 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
382e0 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
382f0 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
38300 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
38310 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
38320 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
38330 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
38340 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
38350 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
38360 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
38370 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
38380 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
38390 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
383a0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
383b0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
383c0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
383d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
383e0 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
383f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
38400 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
38410 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
38420 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
38430 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
38440 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
38450 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73   key */.);.int s
38460 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76 32 28  qlite3_rekey_v2(
38470 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
38480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38490 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
384a0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
384b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
384c0 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20  Name,           
384d0 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64  /* Name of the d
384e0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
384f0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
38500 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
38510 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
38520 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
38530 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
38540 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74  ey for a SEE dat
38550 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
38560 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
38570 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f  ne of the SEE ro
38580 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
38590 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
385a0 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a  3_activate_see(.
385b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
385c0 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
385d0 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
385e0 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
385f0 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  if..#ifdef SQLIT
38600 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f  E_ENABLE_CEROD./
38610 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
38620 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20   activation key 
38630 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61  for a CEROD data
38640 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
38650 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
38660 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72  e of the CEROD r
38670 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
38680 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  k..*/.void sqlit
38690 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f  e3_activate_cero
386a0 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  d(.  const char 
386b0 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
386c0 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
386d0 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
386e0 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
386f0 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
38700 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
38710 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20  hort Time.**.** 
38720 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
38730 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
38740 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
38750 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
38760 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
38770 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
38780 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
38790 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
387a0 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
387b0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
387c0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
387d0 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
387e0 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
387f0 69