System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact eb06a7a2c24836d63607f1a4407c3aaccb79f3cf:


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 23 69 66 6e 64 65 66 20 53 51  ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e  LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e  e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  y are supported 
0800: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
0810: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
0820: 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
0830: 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64  n writers should
0840: 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a   be aware that.*
0850: 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  * experimental i
0860: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
0870: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
0880: 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65  in point release
0890: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d  s..**.** These m
08a0: 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65  acros used to re
08b0: 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73  solve to various
08c0: 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c   kinds of compil
08d0: 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a  er magic that.**
08e0: 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20   would generate 
08f0: 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73  warning messages
0900: 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65 20   when they were 
0910: 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a  used.  But that.
0920: 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  ** compiler magi
0930: 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72  c ended up gener
0940: 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75  ating such a flu
0950: 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72  rry of bug repor
0960: 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61  ts.** that we ha
0970: 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20  ve taken it all 
0980: 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63  out and gone bac
0990: 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c  k to using simpl
09a0: 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73  e.** noop macros
09b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
09c0: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23  ITE_DEPRECATED.#
09d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
09e0: 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a  PERIMENTAL../*.*
09f0: 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20 73  * Ensure these s
0a00: 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20  ymbols were not 
0a10: 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20  defined by some 
0a20: 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 20  previous header 
0a30: 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  file..*/.#ifdef 
0a40: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
0a50: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0a60: 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66  RSION.#endif.#if
0a70: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0a80: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65  ON_NUMBER.# unde
0a90: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0aa0: 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a  _NUMBER.#endif..
0ab0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
0ac0: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62  Compile-Time Lib
0ad0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0ae0: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  bers.**.** ^(The
0af0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0b00: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0b10: 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71   macro in the sq
0b20: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a  lite3.h header.*
0b30: 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61  * evaluates to a
0b40: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
0b50: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69  that is the SQLi
0b60: 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68  te version in th
0b70: 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59  e.** format "X.Y
0b80: 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20 74  .Z" where X is t
0b90: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
0ba0: 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20   number (always 
0bb0: 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33  3 for.** SQLite3
0bc0: 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d  ) and Y is the m
0bd0: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
0be0: 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65  ber and Z is the
0bf0: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e   release number.
0c00: 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  )^.** ^(The [SQL
0c10: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0c20: 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ER] C preprocess
0c30: 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65  or macro resolve
0c40: 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  s to an integer.
0c50: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c 75  ** with the valu
0c60: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0c70: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0c80: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65   X, Y, and Z are
0c90: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d   the same.** num
0ca0: 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51  bers used in [SQ
0cb0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e  LITE_VERSION].)^
0cc0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56  .** The SQLITE_V
0cd0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f  ERSION_NUMBER fo
0ce0: 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65  r any given rele
0cf0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ase of SQLite wi
0d00: 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61  ll also.** be la
0d10: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72 65  rger than the re
0d20: 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  lease from which
0d30: 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e 20   it is derived. 
0d40: 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a   Either Y will.*
0d50: 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61  * be held consta
0d60: 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  nt and Z will be
0d70: 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20   incremented or 
0d80: 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69  else Y will be i
0d90: 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e  ncremented.** an
0da0: 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65  d Z will be rese
0db0: 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t to zero..**.**
0dc0: 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33   Since version 3
0dd0: 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f  .6.18, SQLite so
0de0: 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62 65  urce code has be
0df0: 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  en stored in the
0e00: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
0e10: 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73  p://www.fossil-s
0e20: 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20  cm.org/">Fossil 
0e30: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0e40: 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74  nagement.** syst
0e50: 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51  em</a>.  ^The SQ
0e60: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d  LITE_SOURCE_ID m
0e70: 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74  acro evaluates t
0e80: 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68  o.** a string wh
0e90: 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20 61  ich identifies a
0ea0: 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65 63   particular chec
0eb0: 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a  k-in of SQLite.*
0ec0: 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e  * within its con
0ed0: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
0ee0: 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e  ement system.  ^
0ef0: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  The SQLITE_SOURC
0f00: 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63  E_ID.** string c
0f10: 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 65  ontains the date
0f20: 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65   and time of the
0f30: 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20   check-in (UTC) 
0f40: 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68  and an SHA1.** h
0f50: 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72  ash of the entir
0f60: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a  e source tree..*
0f70: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
0f80: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0f90: 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  on()],.** [sqlit
0fa0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
0fb0: 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65  mber()], [sqlite
0fc0: 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a  3_sourceid()],.*
0fd0: 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  * [sqlite_versio
0fe0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
0ff0: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
1000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1010: 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20  _VERSION        
1020: 22 33 2e 38 2e 38 2e 32 22 0a 23 64 65 66 69 6e  "3.8.8.2".#defin
1030: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
1040: 5f 4e 55 4d 42 45 52 20 33 30 30 38 30 30 38 0a  _NUMBER 3008008.
1050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1060: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 32  OURCE_ID      "2
1070: 30 31 35 2d 30 31 2d 33 30 20 31 34 3a 33 30 3a  015-01-30 14:30:
1080: 34 35 20 37 37 35 37 66 63 37 32 31 32 32 30 65  45 7757fc721220e
1090: 31 33 36 36 32 30 61 38 39 63 39 64 32 38 32 34  136620a89c9d2824
10a0: 37 66 32 38 62 62 62 63 30 39 38 22 0a 0a 2f 2a  7f28bbbc098"../*
10b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
10c0: 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  n-Time Library V
10d0: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a  ersion Numbers.*
10e0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
10f0: 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c  te3_version, sql
1100: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
1110: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
1120: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
1130: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1140: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1150: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1160: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1170: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1180: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1190: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
11a0: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
11b0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
11c0: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
11d0: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
11e0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
11f0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
1200: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
1210: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
1220: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
1230: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1240: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1250: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1260: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1270: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1280: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1290: 2c 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75 72  , and thus insur
12a0: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
12b0: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
12c0: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
12d0: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
12e0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
12f0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1300: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
1310: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1320: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
1330: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1340: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1350: 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33  ( strcmp(sqlite3
1360: 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49  _sourceid(),SQLI
1370: 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30  TE_SOURCE_ID)==0
1380: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1390: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69  trcmp(sqlite3_li
13a0: 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54  bversion(),SQLIT
13b0: 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b  E_VERSION)==0 );
13c0: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
13d0: 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
13e0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72  ^The sqlite3_ver
13f0: 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f  sion[] string co
1400: 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20  nstant contains 
1410: 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c  the text of [SQL
1420: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20  ITE_VERSION].** 
1430: 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c  macro.  ^The sql
1440: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1450: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
1460: 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1470: 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71  the.** to the sq
1480: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20  lite3_version[] 
1490: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e  string constant.
14a0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69    The sqlite3_li
14b0: 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75  bversion().** fu
14c0: 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64  nction is provid
14d0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c  ed for use in DL
14e0: 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65  Ls since DLL use
14f0: 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f  rs usually do no
1500: 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74  t have.** direct
1510: 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e   access to strin
1520: 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68  g constants with
1530: 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68  in the DLL.  ^Th
1540: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62  e.** sqlite3_lib
1550: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
1560: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1570: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75  s an integer equ
1580: 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  al to.** [SQLITE
1590: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
15a0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
15b0: 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74  sourceid() funct
15c0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  ion returns .** 
15d0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
15e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77  tring constant w
15f0: 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68  hose value is th
1600: 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a  e same as the .*
1610: 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  * [SQLITE_SOURCE
1620: 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73  _ID] C preproces
1630: 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  sor macro..**.**
1640: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1650: 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  te_version()] an
1660: 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65  d [sqlite_source
1670: 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  _id()]..*/.SQLIT
1680: 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54  E_API SQLITE_EXT
1690: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
16a0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
16b0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
16c0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
16d0: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64  _libversion(void
16e0: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
16f0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1700: 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29  3_sourceid(void)
1710: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
1720: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1730: 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29  ion_number(void)
1740: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1750: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
1760: 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20  ary Compilation 
1770: 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74  Options Diagnost
1780: 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ics.**.** ^The s
1790: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
17a0: 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63  tion_used() func
17b0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f  tion returns 0 o
17c0: 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69  r 1 .** indicati
17d0: 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73  ng whether the s
17e0: 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20  pecified option 
17f0: 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a  was defined at .
1800: 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  ** compile time.
1810: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70    ^The SQLITE_ p
1820: 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69  refix may be omi
1830: 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a  tted from the .*
1840: 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61  * option name pa
1850: 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ssed to sqlite3_
1860: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1870: 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54  ed().  .**.** ^T
1880: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
1890: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66  leoption_get() f
18a0: 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69  unction allows i
18b0: 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72  terating.** over
18c0: 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74   the list of opt
18d0: 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64  ions that were d
18e0: 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c  efined at compil
18f0: 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74  e time by.** ret
1900: 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20  urning the N-th 
1910: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74  compile time opt
1920: 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66  ion string.  ^If
1930: 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
1940: 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ge,.** sqlite3_c
1950: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1960: 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
1970: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
1980: 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65   SQLITE_ .** pre
1990: 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66  fix is omitted f
19a0: 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20  rom any strings 
19b0: 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20  returned by .** 
19c0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
19d0: 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a  ption_get()..**.
19e0: 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20  ** ^Support for 
19f0: 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66  the diagnostic f
1a00: 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33  unctions sqlite3
1a10: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
1a20: 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c  sed().** and sql
1a30: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1a40: 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20  on_get() may be 
1a50: 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69  omitted by speci
1a60: 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53  fying the .** [S
1a70: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49  QLITE_OMIT_COMPI
1a80: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20  LEOPTION_DIAGS] 
1a90: 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c  option at compil
1aa0: 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  e time..**.** Se
1ab0: 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63  e also: SQL func
1ac0: 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f  tions [sqlite_co
1ad0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ae0: 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1af0: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  te_compileoption
1b00: 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20  _get()] and the 
1b10: 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73  [compile_options
1b20: 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66   pragma]..*/.#if
1b30: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
1b40: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1b50: 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20  IAGS.SQLITE_API 
1b60: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1b70: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63  ileoption_used(c
1b80: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e  onst char *zOptN
1b90: 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ame);.SQLITE_API
1ba0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
1bb0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1bc0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
1bd0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1be0: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1bf0: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
1c00: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
1c10: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c20: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
1c30: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1c40: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
1c50: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
1c60: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1c70: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
1c80: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
1c90: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1ca0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
1cb0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
1cc0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
1cd0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1ce0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1cf0: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
1d00: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
1d10: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1d20: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
1d30: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
1d40: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
1d50: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1d60: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1d70: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1d80: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1d90: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1da0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1db0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1dc0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1dd0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1de0: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1df0: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
1e00: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
1e10: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1e20: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1e30: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1e40: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1e50: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1e60: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1e70: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1e80: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1e90: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1ea0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1eb0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1ec0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1ed0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1ee0: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
1ef0: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
1f00: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
1f10: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1f20: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1f30: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
1f40: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
1f50: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1f60: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1f70: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1f80: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1f90: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1fa0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1fb0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1fc0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1fd0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
1fe0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1ff0: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
2000: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
2010: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
2020: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
2030: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2040: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
2050: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
2060: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
2070: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
2080: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
2090: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
20a0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
20b0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
20c0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
20d0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
20e0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
20f0: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
2100: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
2110: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
2120: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2130: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
2140: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2150: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20  G_SERIALIZED].  
2160: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  ^(The return val
2170: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c  ue of the.** sql
2180: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2190: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  ) function shows
21a0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c   only the compil
21b0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f  e-time setting o
21c0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65  f.** thread safe
21d0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d  ty, not any run-
21e0: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20  time changes to 
21f0: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64  that setting mad
2200: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e by.** sqlite3_
2210: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68  config(). In oth
2220: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65  er words, the re
2230: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2240: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2250: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61  fe().** is uncha
2260: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f  nged by calls to
2270: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
2280: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ).)^.**.** See t
2290: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
22a0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
22b0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
22c0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
22d0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
22e0: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
22f0: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  fe(void);../*.**
2300: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
2310: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48  ase Connection H
2320: 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44  andle.** KEYWORD
2330: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
2340: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
2350: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
2360: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
2370: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
2380: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
2390: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  y a pointer to a
23a0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a  n instance of.**
23b0: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75   the opaque stru
23c0: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c  cture named "sql
23d0: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73  ite3".  It is us
23e0: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66  eful to think of
23f0: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70   an sqlite3.** p
2400: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a  ointer as an obj
2410: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ect.  The [sqlit
2420: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2430: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
2440: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2450: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
2460: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f  faces are its co
2470: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20  nstructors, and 
2480: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2490: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
24a0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72  3_close_v2()] ar
24b0: 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  e its destructor
24c0: 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  s.  There are ma
24d0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65  ny other.** inte
24e0: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
24f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2500: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
2510: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2520: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
2530: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
2540: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
2550: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
2560: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
2570: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
2580: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
2590: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
25a0: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
25b0: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
25c0: 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a  Integer Types.**
25d0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
25e0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  e_int64 sqlite_u
25f0: 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61  int64.**.** Beca
2600: 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20  use there is no 
2610: 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77  cross-platform w
2620: 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34  ay to specify 64
2630: 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70  -bit integer typ
2640: 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63  es.** SQLite inc
2650: 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66  ludes typedefs f
2660: 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  or 64-bit signed
2670: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e   and unsigned in
2680: 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  tegers..**.** Th
2690: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
26a0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  and sqlite3_uint
26b0: 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65  64 are the prefe
26c0: 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69  rred type defini
26d0: 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71  tions..** The sq
26e0: 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73  lite_int64 and s
26f0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2700: 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  es are supported
2710: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a   for backwards.*
2720: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
2730: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  only..**.** ^The
2740: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
2750: 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  nd sqlite_int64 
2760: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20  types can store 
2770: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a  integer values.*
2780: 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33  * between -92233
2790: 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61  72036854775808 a
27a0: 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35  nd +922337203685
27b0: 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76  4775807 inclusiv
27c0: 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
27d0: 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73  te3_uint64 and s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
27f0: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2800: 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20  eger values .** 
2810: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31  between 0 and +1
2820: 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31  8446744073709551
2830: 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a  615 inclusive..*
2840: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
2850: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
2860: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
2870: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
2880: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2890: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
28a0: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
28b0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
28c0: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
28d0: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
28e0: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
28f0: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2900: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2910: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2920: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2930: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2940: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2950: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2960: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2970: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2980: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2990: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
29a0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
29b0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
29c0: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
29d0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
29e0: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
29f0: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2a00: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2a10: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2a20: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2a30: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2a40: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2a50: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2a60: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2a70: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2a80: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2a90: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2aa0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2ab0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2ac0: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
2ad0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2ae0: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2af0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2b00: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2b10: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2b20: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2b30: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2b40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2b50: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2b60: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2b70: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2b80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2b90: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2ba0: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2bb0: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2bc0: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2bd0: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2be0: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2bf0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2c00: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2c10: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2c20: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2c30: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2c40: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2c50: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2c60: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2c70: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2c80: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2c90: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2ca0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2cb0: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2cc0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2cd0: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2ce0: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2cf0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2d00: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2d10: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2d20: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2d30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d40: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2d50: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2d60: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2d70: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2d80: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2d90: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2da0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2db0: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2dc0: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2dd0: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2de0: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2df0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2e00: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2e10: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2e20: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2e30: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2e40: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2e50: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2e60: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2e70: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2e80: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2e90: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2ea0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
2eb0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ec0: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2ed0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ee0: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
2ef0: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
2f00: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
2f10: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
2f20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
2f30: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
2f40: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
2f50: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
2f60: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
2f70: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
2f80: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
2f90: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
2fa0: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
2fb0: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
2fc0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
2fd0: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2fe0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ff0: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3000: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
3010: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3020: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3030: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
3040: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
3050: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
3060: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3070: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3080: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3090: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
30a0: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
30b0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
30c0: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
30d0: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
30e0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
30f0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3100: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3110: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3120: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3130: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
3140: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
3150: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
3160: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3170: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3180: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3190: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
31a0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
31b0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
31c0: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
31d0: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
31e0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
31f0: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3200: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3210: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3220: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3230: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
3240: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
3250: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
3260: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3270: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3280: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3290: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
32a0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
32b0: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
32c0: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
32d0: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
32e0: 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  p..*/.SQLITE_API
32f0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f   int sqlite3_clo
3300: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  se(sqlite3*);.SQ
3310: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
3320: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71  ite3_close_v2(sq
3330: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
3340: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
3350: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
3360: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
3370: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
3380: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
3390: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
33a0: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
33b0: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
33c0: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
33d0: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69  pedef int (*sqli
33e0: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
33f0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
3400: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
3410: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
3420: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
3430: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a  on Interface.**.
3440: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
3450: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3460: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  is a convenience
3470: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
3480: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
3490: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
34a0: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
34b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
34c0: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61  ze()],.** that a
34d0: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61  llows an applica
34e0: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74  tion to run mult
34f0: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20  iple statements 
3500: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75  of SQL.** withou
3510: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20  t having to use 
3520: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
3530: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
3540: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3550: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20  rface runs zero 
3560: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e  or more UTF-8 en
3570: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f  coded,.** semico
3580: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c  lon-separate SQL
3590: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
35a0: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20  ed into its 2nd 
35b0: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20  argument,.** in 
35c0: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
35d0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35e0: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20  nection] passed 
35f0: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a  in as its 1st.**
3600: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
3610: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
3620: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64  ction of the 3rd
3630: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
3640: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3650: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
3660: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66   it is invoked f
3670: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72  or each result r
3680: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74  ow.** coming out
3690: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65   of the evaluate
36a0: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
36b0: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
36c0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
36d0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c  e3_exec() is rel
36e0: 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ayed through to 
36f0: 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74  the 1st argument
3700: 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c   of each.** call
3710: 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  back invocation.
3720: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
3730: 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  ck pointer to sq
3740: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3750: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f  is NULL, then no
3760: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65   callback is eve
3770: 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65  r invoked and re
3780: 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a  sult rows are.**
3790: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
37a0: 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  ^If an error occ
37b0: 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61  urs while evalua
37c0: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61  ting the SQL sta
37d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
37e0: 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  nto.** sqlite3_e
37f0: 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63  xec(), then exec
3800: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
3810: 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73  rent statement s
3820: 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73  tops and.** subs
3830: 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74  equent statement
3840: 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20  s are skipped.  
3850: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
3860: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3870: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f  _exec().** is no
3880: 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20  t NULL then any 
3890: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73  error message is
38a0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
38b0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  mory obtained.**
38c0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
38d0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73  alloc()] and pas
38e0: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68  sed back through
38f0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3900: 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  er..** To avoid 
3910: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68  memory leaks, th
3920: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
3930: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  ould invoke [sql
3940: 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
3950: 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  on error message
3960: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
3970: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  d through the 5t
3980: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a  h parameter of.*
3990: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  * of sqlite3_exe
39a0: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72  c() after the er
39b0: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
39c0: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ng is no longer 
39d0: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  needed..** ^If t
39e0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
39f0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3a00: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  () is not NULL a
3a10: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  nd no errors.** 
3a20: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69  occur, then sqli
3a30: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20  te3_exec() sets 
3a40: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69  the pointer in i
3a50: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  ts 5th parameter
3a60: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f   to.** NULL befo
3a70: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
3a80: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74  .** ^If an sqlit
3a90: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3aa0: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
3ab0: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ero, the sqlite3
3ac0: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69  _exec().** routi
3ad0: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  ne returns SQLIT
3ae0: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20  E_ABORT without 
3af0: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c  invoking the cal
3b00: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a  lback again and.
3b10: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69  ** without runni
3b20: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ng any subsequen
3b30: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
3b40: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64  ..**.** ^The 2nd
3b50: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3b60: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3b70: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3b80: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  n is the.** numb
3b90: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
3ba0: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54   the result.  ^T
3bb0: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3bc0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3bd0: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63  xec().** callbac
3be0: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3bf0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c00: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73  ings obtained as
3c10: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c   if from.** [sql
3c20: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
3c30: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63  ()], one for eac
3c40: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61  h column.  ^If a
3c50: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a  n element of a.*
3c60: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20  * result row is 
3c70: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
3c80: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69  rresponding stri
3c90: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  ng pointer for t
3ca0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
3cb0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
3cc0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
3cd0: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
3ce0: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71  ent to the.** sq
3cf0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3d00: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
3d10: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3d20: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65   strings where e
3d30: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70  ach.** entry rep
3d40: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65  resents the name
3d50: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e   of correspondin
3d60: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  g result column 
3d70: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  as obtained.** f
3d80: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
3d90: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a  umn_name()]..**.
3da0: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70  ** ^If the 2nd p
3db0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3dc0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20  te3_exec() is a 
3dd0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20  NULL pointer, a 
3de0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e  pointer.** to an
3df0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f   empty string, o
3e00: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  r a pointer that
3e10: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77   contains only w
3e20: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72  hitespace and/or
3e30: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74   .** SQL comment
3e40: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73  s, then no SQL s
3e50: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76  tatements are ev
3e60: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20  aluated and the 
3e70: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e  database.** is n
3e80: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
3e90: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a  * Restrictions:.
3ea0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
3eb0: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3ec0: 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  on must insure t
3ed0: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61  hat the 1st para
3ee0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3ef0: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20  _exec().**      
3f00: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f  is a valid and o
3f10: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
3f20: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c  nnection]..** <l
3f30: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f40: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  on must not clos
3f50: 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
3f60: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
3f70: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
3f80: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
3f90: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3fa0: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3fb0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3fc0: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ning..** <li> Th
3fd0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
3fe0: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  st not modify th
3ff0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
4000: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f  text passed into
4010: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64  .**      the 2nd
4020: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
4030: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
4040: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
4050: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
4060: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ul>.*/.SQLITE
4070: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
4080: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
4090: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
40c0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
40d0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
4100: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
4110: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
4120: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
4130: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
4140: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
4150: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4180: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
4190: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
41a0: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
41b0: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
41c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41d0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
41e0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
41f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4200: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4210: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75   KEYWORDS: {resu
4220: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4230: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  ons}.**.** Many 
4240: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
4250: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
4260: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
4270: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
4280: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
4290: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
42a0: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
42b0: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
42c0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
42d0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
42e0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
42f0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
4300: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  so: [extended re
4310: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4320: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  tions].*/.#defin
4330: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
4340: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4350: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4360: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4370: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4390: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
43a0: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
43b0: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
43c0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
43d0: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
43e0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
43f0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
4400: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
4410: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
4420: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
4430: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
4440: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4450: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4460: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4470: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4480: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4490: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
44a0: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
44b0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
44c0: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
44d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
44e0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
44f0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
4500: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
4510: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
4530: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
4540: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4550: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4560: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4570: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4580: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4590: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
45a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
45b0: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
45c0: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
45d0: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
45e0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
45f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4600: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
4610: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
4620: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
4630: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
4640: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4650: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4660: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4670: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4680: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4690: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
46a0: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
46b0: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
46c0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
46d0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
46e0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
46f0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
4700: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
4710: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
4720: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
4730: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
4740: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
4750: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
4760: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
4780: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4790: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
47a0: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
47b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
47c0: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
47d0: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65  /* Database is e
47e0: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  mpty */.#define 
47f0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
4800: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
4810: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
4820: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
4830: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
4840: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
4850: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
4860: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
4870: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4880: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
4890: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
48a0: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
48b0: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
48c0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
48d0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
48e0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
48f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4900: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
4910: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
4920: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
4930: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4940: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
4950: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
4960: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
4970: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
4980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
4990: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
49a0: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
49b0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
49c0: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
49d0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
49e0: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
49f0: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
4a00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4a10: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
4a20: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
4a30: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
4a40: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
4a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a60: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
4a70: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
4a80: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
4a90: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4ab0: 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f  TICE      27   /
4ac0: 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20  * Notifications 
4ad0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4ae0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4af0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20  LITE_WARNING    
4b00: 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67   28   /* Warning
4b10: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4b20: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4b30: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20  SQLITE_ROW      
4b40: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74     100  /* sqlit
4b50: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e  e3_step() has an
4b60: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20  other row ready 
4b70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b80: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30  E_DONE        10
4b90: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  1  /* sqlite3_st
4ba0: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65  ep() has finishe
4bb0: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f  d executing */./
4bc0: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63  * end-of-error-c
4bd0: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  odes */../*.** C
4be0: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65  API3REF: Extende
4bf0: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
4c00: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
4c10: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4c20: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
4c30: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4c40: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4c50: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4c60: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4c70: 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a  e of 30 integer.
4c80: 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  ** [result codes
4c90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4ca0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4cb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4cc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4cd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4ce0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4cf0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d00: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4d10: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4d20: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4d30: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4d40: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4d50: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4d60: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4d70: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4d80: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4d90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4da0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4db0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4dc0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4dd0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4de0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4df0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e00: 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72  hese [extended r
4e10: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65  esult codes] are
4e20: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e30: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e40: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e50: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e60: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4e70: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4e80: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20  _codes()] API.  
4e90: 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64  Or, the extended
4ea0: 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65   code for.** the
4eb0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72   most recent err
4ec0: 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  or can be obtain
4ed0: 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
4ee0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
4ef0: 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65  rcode()]..*/.#de
4f00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f10: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4f20: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f30: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4f40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4f50: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4f60: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4f70: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4f80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4f90: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4fa0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4fb0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4fc0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4fd0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4fe0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4ff0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5000: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
5010: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
5020: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5030: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
5040: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
5050: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
5060: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5070: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5080: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
5090: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
50a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
50b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
50c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
50d0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
50e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
50f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5100: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
5110: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5120: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
5130: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5140: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
5150: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5160: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
5170: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5180: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
5190: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
51a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
51b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51c0: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
51d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
51e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
51f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5200: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
5210: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5220: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
5230: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5240: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
5250: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
5260: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
5270: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5280: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
5290: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
52a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
52b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
52c0: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
52d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
52e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
52f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5300: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
5310: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
5320: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
5330: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5340: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
5350: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5360: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
5370: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5380: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
5390: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
53a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
53b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
53c0: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
53d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
53e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
53f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5400: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20  TE_IOERR_SHMMAP 
5410: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5420: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c  TE_IOERR | (21<<
5430: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5440: 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20  TE_IOERR_SEEK   
5450: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5460: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c  TE_IOERR | (22<<
5470: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5480: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f  TE_IOERR_DELETE_
5490: 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49  NOENT      (SQLI
54a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c  TE_IOERR | (23<<
54b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
54c0: 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20  TE_IOERR_MMAP   
54d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
54e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c  TE_IOERR | (24<<
54f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5500: 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50  TE_IOERR_GETTEMP
5510: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5520: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c  TE_IOERR | (25<<
5530: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5540: 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54  TE_IOERR_CONVPAT
5550: 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  H          (SQLI
5560: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c  TE_IOERR | (26<<
5570: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5580: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
5590: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
55a0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
55b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55c0: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
55d0: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
55e0: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
55f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5600: 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48  LITE_BUSY_SNAPSH
5610: 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51  OT           (SQ
5620: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
5630: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5640: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e  QLITE_CANTOPEN_N
5650: 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53  OTEMPDIR      (S
5660: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5670: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5680: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5690: 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20  _ISDIR          
56a0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
56b0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
56c0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
56d0: 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20  EN_FULLPATH     
56e0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
56f0: 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  EN | (3<<8)).#de
5700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5710: 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20  OPEN_CONVPATH   
5720: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5730: 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OPEN | (4<<8)).#
5740: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5750: 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20  RRUPT_VTAB      
5760: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5770: 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RRUPT | (1<<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 52 45 43 4f 56 45 52 59  EADONLY_RECOVERY
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 31 3c 3c 38 29  EADONLY | (1<<8)
57c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57d0: 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f  _READONLY_CANTLO
57e0: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
57f0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c  _READONLY | (2<<
5800: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5810: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c  TE_READONLY_ROLL
5820: 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  BACK       (SQLI
5830: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33  TE_READONLY | (3
5840: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5850: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42  LITE_READONLY_DB
5860: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51  MOVED        (SQ
5870: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5880: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5890: 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c  SQLITE_ABORT_ROL
58a0: 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28  LBACK          (
58b0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28  SQLITE_ABORT | (
58c0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
58d0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58e0: 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53  _CHECK        (S
58f0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5900: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5910: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5920: 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20  AINT_COMMITHOOK 
5930: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5940: 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  AINT | (2<<8)).#
5950: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5960: 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e  NSTRAINT_FOREIGN
5970: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
5980: 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38  NSTRAINT | (3<<8
5990: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
59a0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e  E_CONSTRAINT_FUN
59b0: 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54  CTION     (SQLIT
59c0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
59d0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
59e0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59f0: 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53  _NOTNULL      (S
5a00: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5a10: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
5a20: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5a30: 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20  AINT_PRIMARYKEY 
5a40: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a50: 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23  AINT | (6<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a70: 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52  NSTRAINT_TRIGGER
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5a90: 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38  NSTRAINT | (7<<8
5aa0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5ab0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49  E_CONSTRAINT_UNI
5ac0: 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54  QUE       (SQLIT
5ad0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ae0: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5af0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b00: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53  _VTAB         (S
5b10: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b20: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5b30: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5b40: 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20  AINT_ROWID      
5b50: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5b60: 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23  AINT |(10<<8)).#
5b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
5b80: 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c  TICE_RECOVER_WAL
5b90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f        (SQLITE_NO
5ba0: 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23  TICE | (1<<8)).#
5bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
5bc0: 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c  TICE_RECOVER_ROL
5bd0: 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f  LBACK (SQLITE_NO
5be0: 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23  TICE | (2<<8)).#
5bf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41  define SQLITE_WA
5c00: 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20  RNING_AUTOINDEX 
5c10: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41        (SQLITE_WA
5c20: 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a  RNING | (1<<8)).
5c30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
5c40: 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20  UTH_USER        
5c50: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5c60: 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f  UTH | (1<<8))../
5c70: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
5c80: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
5c90: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
5ca0: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
5cb0: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
5cc0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
5cd0: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
5ce0: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5cf0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
5d00: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
5d10: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
5d20: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
5d30: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
5d40: 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  thod..*/.#define
5d50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5d60: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
5d70: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
5d80: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5d90: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5da0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5db0: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
5dc0: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
5dd0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5de0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5df0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
5e00: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
5e10: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
5e20: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5e30: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5e40: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
5e50: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
5e60: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
5e70: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5e80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
5e90: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
5ea0: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
5eb0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5ec0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
5ed0: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
5ee0: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
5ef0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5f00: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
5f10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5f20: 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20  00000040  /* Ok 
5f30: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5f40: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5f50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d   SQLITE_OPEN_MEM
5f60: 4f 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78  ORY           0x
5f70: 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20  00000080  /* Ok 
5f80: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5f90: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5fa0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5fb0: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
5fc0: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
5fd0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5fe0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5ff0: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
6000: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
6010: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6020: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
6030: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
6040: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
6050: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6060: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
6070: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
6080: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
6090: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
60a0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
60b0: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
60c0: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
60d0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
60e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
60f0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
6100: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
6110: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6120: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
6130: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
6140: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
6150: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6160: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
6170: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
6180: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
6190: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
61a0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
61b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
61c0: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
61d0: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
61e0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
61f0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6200: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
6210: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
6220: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
6230: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6240: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6250: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
6260: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
6270: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
6280: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6290: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
62a0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
62b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
62c0: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
62d0: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
62e0: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
62f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6300: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
6310: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
6320: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
6330: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
6340: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
6350: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
6360: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
6370: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
6380: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
6390: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
63a0: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65   vector of these
63b0: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
63c0: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
63d0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
63e0: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
63f0: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
6400: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
6410: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
6420: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
6430: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
6440: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
6450: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
6460: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
6470: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
6480: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
6490: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
64a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
64b0: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
64c0: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
64d0: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
64e0: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
64f0: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
6500: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
6510: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
6520: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
6530: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
6540: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
6550: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6560: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
6570: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
6580: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
6590: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
65a0: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
65b0: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
65c0: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
65d0: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
65e0: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
65f0: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
6600: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6610: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
6620: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
6630: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
6640: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
6650: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
6660: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
6670: 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51  Write().  The SQ
6680: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
6690: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70  SAFE_OVERWRITE p
66a0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
66b0: 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f  at.** after rebo
66c0: 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ot following a c
66d0: 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f  rash or power lo
66e0: 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74  ss, the only byt
66f0: 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20  es in a.** file 
6700: 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65  that were writte
6710: 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61  n at the applica
6720: 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74  tion level might
6730: 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a   have changed.**
6740: 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65   and that adjace
6750: 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62  nt bytes, even b
6760: 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20  ytes within the 
6770: 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a  same sector are.
6780: 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ** guaranteed to
6790: 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20   be unchanged.  
67a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
67b0: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
67c0: 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69  N_OPEN.** flag i
67d0: 6e 64 69 63 61 74 65 20 74 68 61 74 20 61 20 66  ndicate that a f
67e0: 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65  ile cannot be de
67f0: 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e  leted when open.
6800: 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f    The.** SQLITE_
6810: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20  IOCAP_IMMUTABLE 
6820: 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74  flag indicates t
6830: 68 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20  hat the file is 
6840: 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20  on.** read-only 
6850: 6d 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74  media and cannot
6860: 20 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e   be changed even
6870: 20 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69   by processes wi
6880: 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70  th.** elevated p
6890: 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64  rivileges..*/.#d
68a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
68b0: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
68c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
68d0: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
68e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
68f0: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
6900: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
6910: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6920: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
6930: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6940: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
6950: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
6960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6970: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
6980: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6990: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
69a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
69b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
69d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
69e0: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
69f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a00: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
6a10: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
6a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a30: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
6a40: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a50: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
6a60: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6a70: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
6a80: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
6a90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6aa0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
6ab0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6ac0: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
6ad0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6ae0: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
6af0: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
6b00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b10: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6b20: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
6b30: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b40: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6b50: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
6b60: 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65  00001000.#define
6b70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d   SQLITE_IOCAP_IM
6b80: 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  MUTABLE         
6b90: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a       0x00002000.
6ba0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6bb0: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
6bc0: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
6bd0: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
6be0: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
6bf0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
6c00: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
6c10: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
6c20: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
6c30: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
6c40: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
6c50: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6c60: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
6c70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6c80: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
6c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ca0: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
6cb0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
6cc0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6cd0: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
6ce0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
6cf0: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
6d00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6d10: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
6d20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6d30: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
6d40: 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a  n Type Flags.**.
6d50: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  ** When SQLite i
6d60: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63  nvokes the xSync
6d70: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a  () method of an.
6d80: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6d90: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69  ethods] object i
6da0: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61  t uses a combina
6db0: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65  tion of.** these
6dc0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6dd0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
6de0: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
6df0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
6e00: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
6e10: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
6e20: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
6e30: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
6e40: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
6e50: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
6e60: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
6e70: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
6e80: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
6e90: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  d. If the lower 
6ea0: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65  four bits of the
6eb0: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53   flag.** equal S
6ec0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6ed0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f  L, that means to
6ee0: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
6ef0: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a  c() semantics..*
6f00: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  * If the lower f
6f10: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53  our bits equal S
6f20: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
6f30: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
6f40: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73  o use Mac OS X s
6f50: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
6f60: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
6f70: 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63  ..**.** Do not c
6f80: 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54  onfuse the SQLIT
6f90: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6fa0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6fb0: 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68  LL flags.** with
6fc0: 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e   the [PRAGMA syn
6fd0: 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c  chronous]=NORMAL
6fe0: 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e   and [PRAGMA syn
6ff0: 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a  chronous]=FULL.*
7000: 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65  * settings.  The
7010: 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72   [synchronous pr
7020: 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73  agma] determines
7030: 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74   when calls to t
7040: 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20  he.** xSync VFS 
7050: 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64  method occur and
7060: 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d   applies uniform
7070: 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c  ly across all pl
7080: 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20  atforms..** The 
7090: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
70a0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
70b0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65  NC_FULL flags de
70c0: 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65  termine how.** e
70d0: 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f  nergetic or rigo
70e0: 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c  rous or forceful
70f0: 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74   the sync operat
7100: 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20  ions are and.** 
7110: 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66  only make a diff
7120: 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53  erence on Mac OS
7130: 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c  X for the defaul
7140: 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a  t SQLite code..*
7150: 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56  * (Third-party V
7160: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7170: 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61  ns might also ma
7180: 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
7190: 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
71a0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
71b0: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
71c0: 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67  _FULL, but among
71d0: 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e   the.** operatin
71e0: 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65  g systems native
71f0: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  ly supported by 
7200: 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63  SQLite, only Mac
7210: 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62   OSX.** cares ab
7220: 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e  out the differen
7230: 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ce.).*/.#define 
7240: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7250: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
7260: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7270: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
7280: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
7290: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
72a0: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
72b0: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
72c0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
72d0: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
72e0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  ndle.**.** An [s
72f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7300: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
7310: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
7320: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
7330: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
7340: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
7350: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
7360: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
7370: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
7380: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
7390: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
73a0: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
73b0: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
73c0: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
73d0: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
73e0: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
73f0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
7400: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7410: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
7420: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
7430: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
7440: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
7450: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
7460: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
7470: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
7480: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
7490: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
74a0: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
74b0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
74c0: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
74d0: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
74e0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
74f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7500: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7510: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
7520: 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  hods Object.**.*
7530: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65  * Every file ope
7540: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
7550: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7560: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20  ethod populates 
7570: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  an.** [sqlite3_f
7580: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c  ile] object (or,
7590: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20   more commonly, 
75a0: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
75b0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
75c0: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68  le] object) with
75d0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
75e0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
75f0: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69  s object..** Thi
7600: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
7610: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
7620: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
7630: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a  ious operations.
7640: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ** against the o
7650: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65  pen file represe
7660: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  nted by the [sql
7670: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7680: 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
7690: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
76a0: 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20  en] method sets 
76b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
76c0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
76d0: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
76e0: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
76f0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
7700: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
7710: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
7720: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
7730: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7740: 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65  s.xOpen] reporte
7750: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
7760: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
7770: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
7780: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
7790: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
77a0: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  d [sqlite3_vfs.x
77b0: 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20  Open].** is for 
77c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
77d0: 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74  .xOpen] to set t
77e0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
77f0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7800: 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  .** to NULL..**.
7810: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
7820: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
7830: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
7840: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7850: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
7860: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
7870: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
7880: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
7890: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
78a0: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
78b0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
78c0: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
78d0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
78e0: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
78f0: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
7900: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
7910: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
7920: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
7930: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
7940: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
7950: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
7960: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
7970: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
7980: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
7990: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
79a0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
79b0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
79c0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
79d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
79e0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
79f0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a00: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
7a10: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7a20: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
7a30: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
7a40: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
7a50: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
7a60: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
7a70: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
7a80: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7a90: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
7aa0: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
7ab0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
7ac0: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
7ad0: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
7ae0: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
7af0: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
7b00: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
7b10: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
7b20: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
7b30: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
7b40: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
7b50: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
7b60: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
7b70: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
7b80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7b90: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
7ba0: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
7bb0: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
7bc0: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
7bd0: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
7be0: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
7bf0: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
7c00: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
7c10: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
7c20: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
7c30: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
7c40: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
7c50: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
7c60: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
7c70: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
7c80: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
7c90: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
7ca0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
7cb0: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
7cc0: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
7cd0: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
7ce0: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
7cf0: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
7d00: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
7d10: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
7d20: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
7d30: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
7d40: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
7d50: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
7d60: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
7d70: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
7d80: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
7d90: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
7da0: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
7db0: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
7dc0: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
7dd0: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
7de0: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
7df0: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
7e00: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
7e10: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
7e20: 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20  use..** A [file 
7e30: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
7e40: 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65  | list of opcode
7e50: 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  s] less than 100
7e60: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
7e70: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
7e80: 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73  hat define a cus
7e90: 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  tom xFileControl
7ea0: 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75   method should u
7eb0: 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72  se opcodes.** gr
7ec0: 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74  eater than 100 t
7ed0: 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74  o avoid conflict
7ee0: 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  s.  VFS implemen
7ef0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a  tations should.*
7f00: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
7f10: 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66  _NOTFOUND] for f
7f20: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
7f30: 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f  des that they do
7f40: 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a   not.** recogniz
7f50: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65  e..**.** The xSe
7f60: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f  ctorSize() metho
7f70: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65  d returns the se
7f80: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65  ctor size of the
7f90: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
7fa0: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69  underlies the fi
7fb0: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20  le.  The sector 
7fc0: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d  size is the.** m
7fd0: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61  inimum write tha
7fe0: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  t can be perform
7ff0: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75  ed without distu
8000: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62  rbing.** other b
8010: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
8020: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68  .  The xDeviceCh
8030: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a  aracteristics().
8040: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
8050: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64  s a bit vector d
8060: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69  escribing behavi
8070: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e  ors of the.** un
8080: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a  derlying device:
8090: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
80a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
80b0: 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69  P_ATOMIC].** <li
80c0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
80d0: 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c  ATOMIC512].** <l
80e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
80f0: 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC1K].** <l
8100: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8110: 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC2K].** <l
8120: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8130: 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC4K].** <l
8140: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8150: 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC8K].** <l
8160: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8170: 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c  _ATOMIC16K].** <
8180: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8190: 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20  P_ATOMIC32K].** 
81a0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
81b0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a  AP_ATOMIC64K].**
81c0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
81d0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d  CAP_SAFE_APPEND]
81e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
81f0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
8200: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  L].** </ul>.**.*
8210: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
8220: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
8230: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
8240: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
8250: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
8260: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
8270: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
8280: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
8290: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
82a0: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
82b0: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
82c0: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
82d0: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
82e0: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
82f0: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
8300: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
8310: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
8320: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
8330: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
8340: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
8350: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
8360: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
8370: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
8380: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
8390: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
83a0: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
83b0: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
83c0: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
83d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
83e0: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
83f0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
8400: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
8410: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
8420: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
8430: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
8440: 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49  Write()..**.** I
8450: 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e  f xRead() return
8460: 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  s SQLITE_IOERR_S
8470: 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73  HORT_READ it mus
8480: 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69  t also fill.** i
8490: 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72  n the unread por
84a0: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66  tions of the buf
84b0: 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20  fer with zeros. 
84c0: 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66   A VFS that.** f
84d0: 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  ails to zero-fil
84e0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69  l short reads mi
84f0: 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b  ght seem to work
8500: 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
8510: 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66  ailure to zero-f
8520: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
8530: 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20  will eventually 
8540: 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62  lead to.** datab
8550: 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  ase corruption..
8560: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
8570: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
8580: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f  hods sqlite3_io_
8590: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
85a0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
85b0: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  ds {.  int iVers
85c0: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  ion;.  int (*xCl
85d0: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ose)(sqlite3_fil
85e0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  e*);.  int (*xRe
85f0: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ad)(sqlite3_file
8600: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  *, void*, int iA
8610: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
8620: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
8630: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65  (*xWrite)(sqlite
8640: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76  3_file*, const v
8650: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
8660: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8670: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54  fst);.  int (*xT
8680: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33  runcate)(sqlite3
8690: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
86a0: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69  int64 size);.  i
86b0: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
86c0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66  te3_file*, int f
86d0: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
86e0: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65  FileSize)(sqlite
86f0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8700: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a  _int64 *pSize);.
8710: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73    int (*xLock)(s
8720: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8730: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c  t);.  int (*xUnl
8740: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8750: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8760: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  (*xCheckReserved
8770: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8780: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  le*, int *pResOu
8790: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  t);.  int (*xFil
87a0: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
87b0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
87c0: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
87d0: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
87e0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
87f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
8800: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
8810: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
8820: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8830: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8840: 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f  for version 1 */
8850: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70  .  int (*xShmMap
8860: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8870: 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67   int iPg, int pg
8880: 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f  sz, int, void vo
8890: 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74  latile**);.  int
88a0: 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c   (*xShmLock)(sql
88b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
88c0: 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69  offset, int n, i
88d0: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69  nt flags);.  voi
88e0: 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29  d (*xShmBarrier)
88f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8900: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d  .  int (*xShmUnm
8910: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
8920: 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61  *, int deleteFla
8930: 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  g);.  /* Methods
8940: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8950: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a   for version 2 *
8960: 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68  /.  int (*xFetch
8970: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8980: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8990: 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20  Ofst, int iAmt, 
89a0: 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e  void **pp);.  in
89b0: 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71  t (*xUnfetch)(sq
89c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
89d0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
89e0: 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a  , void *p);.  /*
89f0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8a00: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8a10: 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41  sion 3 */.  /* A
8a20: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64  dditional method
8a30: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
8a40: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
8a50: 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
8a60: 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72  API3REF: Standar
8a70: 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f  d File Control O
8a80: 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  pcodes.** KEYWOR
8a90: 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f  DS: {file contro
8aa0: 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65  l opcodes} {file
8ab0: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d   control opcode}
8ac0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
8ad0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61  eger constants a
8ae0: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74  re opcodes for t
8af0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8b00: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
8b10: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
8b20: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64  hods] object and
8b30: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
8b40: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8b50: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a  ].** interface..
8b60: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
8b70: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8b80: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
8b90: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
8ba0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
8bb0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
8bc0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8bd0: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
8be0: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
8bf0: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
8c00: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
8c10: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
8c20: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
8c30: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8c40: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
8c50: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
8c60: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
8c70: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
8c80: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
8c90: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
8ca0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
8cb0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
8cc0: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
8cd0: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c   testing and onl
8ce0: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
8cf0: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
8d00: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64  ITE_TEST.** is d
8d10: 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a  efined..** <ul>.
8d20: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8d30: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8d40: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8d50: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8d60: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8d70: 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69   by SQLite to gi
8d80: 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61  ve the VFS.** la
8d90: 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f  yer a hint of ho
8da0: 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61  w large the data
8db0: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67  base file will g
8dc0: 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67  row to be during
8dd0: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
8de0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68  transaction.  Th
8df0: 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67  is hint is not g
8e00: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
8e10: 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a  accurate but it.
8e20: 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73  ** is often clos
8e30: 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  e.  The underlyi
8e40: 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f  ng VFS might cho
8e50: 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61  ose to prealloca
8e60: 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  te database.** f
8e70: 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20  ile space based 
8e80: 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20  on this hint in 
8e90: 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72  order to help wr
8ea0: 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61  ites to the data
8eb0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e  base.** file run
8ec0: 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c   faster..**.** <
8ed0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8ee0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a  L_CHUNK_SIZE]].*
8ef0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8f00: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20  NTL_CHUNK_SIZE] 
8f10: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
8f20: 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74  o request that t
8f30: 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64  he VFS.** extend
8f40: 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20  s and truncates 
8f50: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8f60: 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61  e in chunks of a
8f70: 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a   size specified.
8f80: 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20  ** by the user. 
8f90: 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
8fa0: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
8fb0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8fc0: 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74  should .** point
8fd0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28   to an integer (
8fe0: 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69  type int) contai
8ff0: 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75  ning the new chu
9000: 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a  nk-size to use.*
9010: 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61  * for the nomina
9020: 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c  ted database. Al
9030: 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73  locating databas
9040: 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20  e file space in 
9050: 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20  large.** chunks 
9060: 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69  (say 1MB at a ti
9070: 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20  me), may reduce 
9080: 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67  file-system frag
9090: 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  mentation and.**
90a0: 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
90b0: 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73  ance on some sys
90c0: 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tems..**.** <li>
90d0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  [[SQLITE_FCNTL_F
90e0: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  ILE_POINTER]].**
90f0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9100: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
9110: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9120: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e  to obtain a poin
9130: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
9140: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
9150: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  ect associated w
9160: 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
9170: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9180: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68  nection.  See th
9190: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
91a0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d  control()] docum
91b0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
91c0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
91d0: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  mation..**.** <l
91e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
91f0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
9200: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
9210: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
9220: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9230: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
9240: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
9250: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9260: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9270: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
9280: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9290: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
92a0: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
92b0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
92c0: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
92d0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
92e0: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
92f0: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
9300: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
9310: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
9320: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
9330: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
9340: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
9350: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
9360: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
9370: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
9380: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9390: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
93a0: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
93b0: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
93c0: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
93d0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
93e0: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
93f0: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
9400: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
9410: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
9420: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
9430: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
9440: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
9450: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
9460: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
9470: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
9480: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9490: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
94a0: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
94b0: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
94c0: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
94d0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
94e0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
94f0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
9500: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9510: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9520: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9530: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9540: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
9550: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9560: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9570: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9580: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9590: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
95a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
95b0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
95c0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
95d0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
95e0: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
95f0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
9600: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
9610: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
9620: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
9630: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
9640: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9650: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9660: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9670: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
9680: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9690: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
96a0: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
96b0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
96c0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
96d0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
96e0: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
96f0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9700: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
9710: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9720: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9730: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
9740: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9750: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9760: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9770: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9780: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9790: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
97a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
97b0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
97c0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
97d0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
97e0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
97f0: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
9800: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
9810: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
9820: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
9830: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
9840: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
9850: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
9860: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
9870: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
9880: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9890: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
98a0: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
98b0: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
98c0: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
98d0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
98e0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
98f0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
9900: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
9910: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
9920: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
9930: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
9940: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
9950: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
9960: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
9970: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
9980: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9990: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
99a0: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
99b0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
99c0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
99d0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
99e0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
99f0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
9a00: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
9a10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9a20: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
9a30: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
9a40: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
9a50: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9a60: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
9a70: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9a80: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9a90: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9aa0: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
9ab0: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
9ac0: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
9ad0: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
9ae0: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
9af0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9b00: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9b10: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9b20: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9b30: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9b40: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9b50: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9b60: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9b70: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9b80: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9b90: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
9ba0: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
9bb0: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
9bc0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9bd0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9be0: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
9bf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9c00: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9c10: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9c20: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9c30: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
9c40: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
9c50: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
9c60: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
9c70: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
9c80: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
9c90: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9ca0: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
9cb0: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
9cc0: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
9cd0: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
9ce0: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
9cf0: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
9d00: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
9d10: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
9d20: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
9d30: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
9d40: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
9d50: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
9d60: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
9d70: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
9d80: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
9d90: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
9da0: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
9db0: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
9dc0: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
9dd0: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
9de0: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
9df0: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
9e00: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
9e10: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
9e20: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
9e30: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
9e40: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
9e50: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
9e60: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
9e70: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9e80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9e90: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9ea0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9eb0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
9ec0: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
9ed0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
9ee0: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
9ef0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
9f00: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
9f10: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
9f20: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9f30: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9f40: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9f50: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
9f60: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
9f70: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
9f80: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9f90: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
9fa0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
9fb0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9fc0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
9fd0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
9fe0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9ff0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
a000: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
a010: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
a020: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
a030: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
a040: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
a050: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
a060: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
a070: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
a080: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
a090: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
a0a0: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
a0b0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a0c0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a0d0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a0e0: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a0f0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a100: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a110: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a120: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a130: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
a140: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a150: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
a160: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a170: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a180: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a190: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a1a0: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
a1b0: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
a1c0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a1d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a1e0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a1f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a200: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a210: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
a220: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
a230: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
a240: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
a250: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
a260: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
a270: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
a280: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
a290: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
a2a0: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
a2b0: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
a2c0: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
a2d0: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
a2e0: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
a2f0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
a300: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a310: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
a320: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a330: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
a340: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
a350: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
a360: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
a370: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
a380: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
a390: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
a3a0: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
a3b0: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
a3c0: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
a3d0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
a3e0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
a3f0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
a400: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
a410: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
a420: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a430: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
a440: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a450: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
a460: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
a470: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
a480: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
a490: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
a4a0: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
a4b0: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
a4c0: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
a4d0: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
a4e0: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
a4f0: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
a500: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
a510: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
a520: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
a530: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
a540: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
a550: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
a560: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
a570: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
a580: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
a590: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
a5a0: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
a5b0: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
a5c0: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
a5d0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a5e0: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
a5f0: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
a600: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
a610: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
a620: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
a630: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
a640: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
a650: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
a660: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
a670: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
a680: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
a690: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
a6a0: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
a6b0: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
a6c0: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
a6d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a6e0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a6f0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
a700: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
a710: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
a720: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
a730: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
a740: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
a750: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
a760: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
a770: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
a780: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
a790: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
a7a0: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
a7b0: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
a7c0: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
a7d0: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
a7e0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a7f0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
a800: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
a810: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
a820: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
a830: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
a840: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
a850: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
a860: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
a870: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
a880: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
a890: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
a8a0: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
a8b0: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
a8c0: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
a8d0: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
a8e0: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
a8f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
a900: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a910: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
a920: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
a930: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
a940: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
a950: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
a960: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
a970: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
a980: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a990: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a9a0: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
a9b0: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
a9c0: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
a9d0: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
a9e0: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
a9f0: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
aa00: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
aa10: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
aa20: 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  t.  ^If the [SQL
aa30: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
aa40: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
aa50: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
aa60: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
aa70: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
aa80: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
aa90: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
aaa0: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
aab0: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
aac0: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
aad0: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
aae0: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
aaf0: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
ab00: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
ab10: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
ab20: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ab30: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
ab40: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
ab50: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
ab60: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
ab70: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
ab80: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
ab90: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
aba0: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
abb0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
abc0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
abd0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
abe0: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
abf0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
ac00: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
ac10: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
ac20: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
ac30: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
ac40: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
ac50: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
ac60: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
ac70: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
ac80: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
ac90: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
aca0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
acb0: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
acc0: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
acd0: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
ace0: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
acf0: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
ad00: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
ad10: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
ad20: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
ad30: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
ad40: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
ad50: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
ad60: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
ad70: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
ad80: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
ad90: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
ada0: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
adb0: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
adc0: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
add0: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
ade0: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
adf0: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
ae00: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
ae10: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
ae20: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
ae30: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
ae40: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
ae50: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
ae60: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
ae70: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
ae80: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ae90: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
aea0: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
aeb0: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
aec0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aed0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
aee0: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
aef0: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
af00: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
af10: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
af20: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
af30: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
af40: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
af50: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
af60: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
af70: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
af80: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
af90: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
afa0: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
afb0: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
afc0: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
afd0: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
afe0: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
aff0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
b000: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
b010: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
b020: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
b030: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
b040: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
b050: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
b060: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
b070: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b080: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
b090: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b0a0: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b0b0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b0c0: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
b0d0: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
b0e0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b0f0: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
b100: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
b110: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
b120: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b130: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b140: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
b150: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
b160: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
b170: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
b180: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
b190: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
b1a0: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
b1b0: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
b1c0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
b1d0: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
b1e0: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
b1f0: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
b200: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
b210: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
b220: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
b230: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
b240: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
b250: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
b260: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
b270: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
b280: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
b290: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
b2a0: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
b2b0: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
b2c0: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
b2d0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b2e0: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
b2f0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b300: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
b310: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
b320: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
b330: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
b340: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
b350: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
b360: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
b370: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
b380: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
b390: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
b3a0: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
b3b0: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
b3c0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
b3d0: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
b3e0: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
b3f0: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
b400: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
b410: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
b420: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
b430: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
b440: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
b450: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
b460: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
b470: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
b480: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b490: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b4a0: 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VED]].** The [SQ
b4b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
b4c0: 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72  OVED] file contr
b4d0: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
b4e0: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a  s argument as a.
b4f0: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
b500: 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20   integer and it 
b510: 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e  writes a boolean
b520: 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
b530: 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  er depending.** 
b540: 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
b550: 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62  t the file has b
b560: 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76  een renamed, mov
b570: 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73  ed, or deleted s
b580: 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66  ince it.** was f
b590: 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  irst opened..**.
b5a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b5b0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
b5c0: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
b5d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
b5e0: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_SET_HANDLE] 
b5f0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
b600: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
b610: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
b620: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
b630: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
b640: 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61  swap the file ha
b650: 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e  ndle with the on
b660: 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  e.** pointed to 
b670: 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75  by the pArg argu
b680: 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61  ment.  This capa
b690: 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64  bility is used d
b6a0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a  uring testing.**
b6b0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
b6c0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
b6d0: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
b6e0: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a   is defined..**.
b6f0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
b700: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b710: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
b720: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
b730: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
b740: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
b750: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
b760: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43  e SQLITE_SET_LOC
b770: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
b780: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
b790: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
b7a0: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
b7b0: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
b7c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
b7d0: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
b7e0: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
b7f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
b800: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
b810: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
b820: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
b830: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
b840: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
b850: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
b860: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
b870: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
b880: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
b890: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
b8a0: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
b8b0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
b8c0: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
b8d0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b8e0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
b8f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
b900: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b910: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
b920: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
b930: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b940: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
b950: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
b960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b970: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
b980: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
b990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b9a0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
b9b0: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
b9c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b9d0: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
b9e0: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
b9f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ba00: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
ba10: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
ba20: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ba30: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
ba40: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
ba50: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
ba60: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
ba70: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
ba80: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
ba90: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
baa0: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
bab0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
bac0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
bad0: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53      22.#define S
bae0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
baf0: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_SET_HANDLE    
bb00: 20 20 20 32 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     23../*.** CAP
bb10: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e  I3REF: Mutex Han
bb20: 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  dle.**.** The mu
bb30: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
bb40: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
bb50: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
bb60: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
bb70: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
bb80: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
bb90: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
bba0: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
bbb0: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
bbc0: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
bbd0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
bbe0: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
bbf0: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
bc00: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
bc10: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
bc20: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
bc30: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
bc40: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
bc50: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
bc60: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
bc70: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
bc80: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
bc90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
bca0: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
bcb0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
bcc0: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
bcd0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
bce0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
bcf0: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
bd00: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
bd10: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
bd20: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
bd30: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
bd40: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
bd50: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
bd60: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
bd70: 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65  ile system".  Se
bd80: 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20  e.** the [VFS | 
bd90: 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  VFS documentatio
bda0: 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69  n] for further i
bdb0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
bdc0: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
bdd0: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
bde0: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
bdf0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
be00: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
be10: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
be20: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
be30: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
be40: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
be50: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
be60: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
be70: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
be80: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
be90: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
bea0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
beb0: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
bec0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
bed0: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
bee0: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
bef0: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
bf00: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
bf10: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
bf20: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
bf30: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
bf40: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
bf50: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
bf60: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
bf70: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
bf80: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
bf90: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
bfa0: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
bfb0: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
bfc0: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
bfd0: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
bfe0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
bff0: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
c000: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
c010: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
c020: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
c030: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
c040: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
c050: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
c060: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
c070: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
c080: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
c090: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
c0a0: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
c0b0: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
c0c0: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
c0d0: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
c0e0: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
c0f0: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
c100: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
c110: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
c120: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
c130: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
c140: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
c150: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
c160: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
c170: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
c180: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
c190: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
c1a0: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
c1b0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
c1c0: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
c1d0: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
c1e0: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
c1f0: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
c200: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
c210: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
c220: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
c230: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
c240: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
c250: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
c260: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
c270: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
c280: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
c290: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
c2a0: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
c2b0: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
c2c0: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
c2d0: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  modules..**.** [
c2e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
c2f0: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  en]].** ^SQLite 
c300: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
c310: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
c320: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
c330: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
c340: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
c350: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
c360: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
c370: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20  hname() with an 
c380: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20  optional suffix 
c390: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20  added..** ^If a 
c3a0: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20  suffix is added 
c3b0: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  to the zFilename
c3c0: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77   parameter, it w
c3d0: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f  ill.** consist o
c3e0: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63  f a single "-" c
c3f0: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65  haracter followe
c400: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61  d by no more tha
c410: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d  n.** 11 alphanum
c420: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20  eric and/or "-" 
c430: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e  characters..** ^
c440: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
c450: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
c460: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
c470: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
c480: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
c490: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
c4a0: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
c4b0: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
c4c0: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
c4d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
c4e0: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
c4f0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
c500: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
c510: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
c520: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
c530: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
c540: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
c550: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
c560: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  to xOpen is a NU
c570: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
c580: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
c590: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
c5a0: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
c5b0: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e  the file.  ^When
c5c0: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69  ever the .** xFi
c5d0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c5e0: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c   is NULL it will
c5f0: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73   also be the cas
c600: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c  e that the.** fl
c610: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69  ags parameter wi
c620: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ll include [SQLI
c630: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
c640: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  CLOSE]..**.** Th
c650: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
c660: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
c670: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
c680: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
c690: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
c6a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
c6b0: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
c6c0: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
c6d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
c6e0: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
c6f0: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
c700: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
c710: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
c720: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
c730: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a  PEN_CREATE]. .**
c740: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
c750: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
c760: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
c770: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
c780: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
c790: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
c7a0: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
c7b0: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
c7c0: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53  e set..**.** ^(S
c7d0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
c7e0: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
c7f0: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
c800: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
c810: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
c820: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
c830: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
c840: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
c850: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
c860: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
c870: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
c880: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
c890: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c8a0: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
c8b0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c8c0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
c8d0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c8e0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
c8f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c900: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
c910: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
c920: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
c930: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
c940: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c950: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  WAL].** </ul>)^.
c960: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
c970: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
c980: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
c990: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
c9a0: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
c9b0: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
c9c0: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
c9d0: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
c9e0: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
c9f0: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
ca00: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
ca10: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
ca20: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
ca30: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
ca40: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
ca50: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
ca60: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
ca70: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
ca80: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
ca90: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
caa0: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
cab0: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
cac0: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
cad0: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
cae0: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
caf0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
cb00: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
cb10: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
cb20: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
cb30: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
cb40: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
cb50: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
cb60: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
cb70: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
cb80: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
cb90: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
cba0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
cbb0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
cbc0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
cbd0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
cbe0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
cbf0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
cc00: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
cc10: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
cc20: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
cc30: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
cc40: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
cc50: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
cc60: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
cc70: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20  s closed.  ^The 
cc80: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
cc90: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77  ETEONCLOSE].** w
cca0: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54  ill be set for T
ccb0: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e  EMP databases an
ccc0: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73  d their journals
ccd0: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64  , transient.** d
cce0: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75  atabases, and su
ccf0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
cd00: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
cd10: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
cd20: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  ag is always use
cd30: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e  d in conjunction
cd40: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
cd50: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
cd60: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72  ] flag, which ar
cd70: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a  e both directly.
cd80: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20  ** analogous to 
cd90: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f  the O_EXCL and O
cda0: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20  _CREAT flags of 
cdb0: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29  the POSIX open()
cdc0: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51  .** API.  The SQ
cdd0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
cde0: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70  IVE flag, when p
cdf0: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a  aired with the .
ce00: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ** SQLITE_OPEN_C
ce10: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74  REATE, is used t
ce20: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
ce30: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61  file should alwa
ce40: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64  ys.** be created
ce50: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73  , and that it is
ce60: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20   an error if it 
ce70: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a  already exists..
ce80: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c  ** It is <i>not<
ce90: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69  /i> used to indi
cea0: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68  cate the file sh
ceb0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a  ould be opened .
cec0: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
ced0: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e   access..**.** ^
cee0: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
cef0: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
cf00: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
cf10: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
cf20: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
cf30: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
cf40: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
cf50: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
cf60: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
cf70: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
cf80: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
cf90: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
cfa0: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
cfb0: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
cfc0: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
cfd0: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
cfe0: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
cff0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
d000: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
d010: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
d020: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
d030: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
d040: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
d050: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
d060: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
d070: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
d080: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
d090: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
d0a0: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
d0b0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
d0c0: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
d0d0: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
d0e0: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
d0f0: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
d100: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
d110: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
d120: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65  Access]].** ^The
d130: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
d140: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
d150: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
d160: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
d170: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
d180: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
d190: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
d1a0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
d1b0: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
d1c0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
d1d0: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
d1e0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
d1f0: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
d200: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
d210: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
d220: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
d230: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
d240: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
d250: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
d260: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
d270: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
d280: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
d290: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
d2a0: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
d2b0: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20  ame.  The exact 
d2c0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
d2d0: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
d2e0: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
d2f0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
d300: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  th  methods. If 
d310: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
d320: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
d330: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
d340: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
d350: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
d360: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
d370: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
d380: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
d390: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
d3a0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
d3b0: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
d3c0: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
d3d0: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
d3e0: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
d3f0: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
d400: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
d410: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
d420: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65  (), xCurrentTime
d430: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
d440: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69  TimeInt64().** i
d450: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
d460: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
d470: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
d480: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
d490: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
d4a0: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
d4b0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
d4c0: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
d4d0: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
d4e0: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
d4f0: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
d500: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
d510: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
d520: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
d530: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
d540: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
d550: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
d560: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
d570: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
d580: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
d590: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
d5a0: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
d5b0: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
d5c0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
d5d0: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
d5e0: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e  n.  ^The xCurren
d5f0: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
d600: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
d610: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
d620: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
d630: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a  te and time as.*
d640: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  * a floating poi
d650: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68  nt value..** ^Th
d660: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
d670: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74  t64() method ret
d680: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65  urns, as an inte
d690: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a  ger, the Julian.
d6a0: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75  ** Day Number mu
d6b0: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30  ltiplied by 8640
d6c0: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72  0000 (the number
d6d0: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
d6e0: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75   in .** a 24-hou
d6f0: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51  r day).  .** ^SQ
d700: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
d710: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
d720: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20  t64() method to 
d730: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a  get the current.
d740: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
d750: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20   if that method 
d760: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66  is available (if
d770: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f   iVersion is 2 o
d780: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e  r .** greater an
d790: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  d the function p
d7a0: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
d7b0: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c  LL) and will fal
d7c0: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75  l back.** to xCu
d7d0: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78  rrentTime() if x
d7e0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
d7f0: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  () is unavailabl
d800: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53  e..**.** ^The xS
d810: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
d820: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xGetSystemCall()
d830: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65  , and xNestSyste
d840: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  mCall() interfac
d850: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73  es.** are not us
d860: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65  ed by the SQLite
d870: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70   core.  These op
d880: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65  tional interface
d890: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a  s are provided.*
d8a0: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20  * by some VFSes 
d8b0: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65  to facilitate te
d8c0: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53  sting of the VFS
d8d0: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69   code. By overri
d8e0: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20  ding .** system 
d8f0: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74  calls with funct
d900: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63  ions under its c
d910: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70  ontrol, a test p
d920: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69  rogram can.** si
d930: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e  mulate faults an
d940: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  d error conditio
d950: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74  ns that would ot
d960: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69  herwise be diffi
d970: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73  cult.** or impos
d980: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e  sible to induce.
d990: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73    The set of sys
d9a0: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63  tem calls that c
d9b0: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
d9c0: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20  .** varies from 
d9d0: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68  one VFS to anoth
d9e0: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65  er, and from one
d9f0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
da00: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a  same VFS to the.
da10: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
da20: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
da30: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
da40: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65   must be prepare
da50: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20  d for any.** or 
da60: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74  all of these int
da70: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55  erfaces to be NU
da80: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20  LL or for their 
da90: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e  behavior to chan
daa0: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72  ge.** from one r
dab0: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
dac0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
dad0: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d  s must not attem
dae0: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20  pt to access.** 
daf0: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74  any of these met
db00: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72  hods if the iVer
db10: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20  sion of the VFS 
db20: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a  is less than 3..
db30: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
db40: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
db50: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64  lite3_vfs;.typed
db60: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
db70: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76  3_syscall_ptr)(v
db80: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c  oid);.struct sql
db90: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
dba0: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
dbb0: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
dbc0: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
dbd0: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20  r (currently 3) 
dbe0: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
dbf0: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
dc00: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
dc10: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
dc20: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
dc30: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
dc40: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
dc50: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
dc60: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
dc70: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
dc80: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
dc90: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
dca0: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
dcb0: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
dcc0: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
dcd0: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
dce0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
dcf0: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
dd00: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
dd10: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
dd20: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
dd30: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
dd40: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
dd50: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
dd60: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
dd70: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
dd80: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
dd90: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
dda0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ddb0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
ddc0: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
ddd0: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
dde0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ddf0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
de00: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
de10: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
de20: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
de30: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
de40: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
de50: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
de60: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
de70: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
de80: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
de90: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
dea0: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
deb0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
dec0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
ded0: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
dee0: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
def0: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
df00: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
df10: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
df20: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
df30: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
df40: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
df50: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
df60: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
df70: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
df80: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
df90: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
dfa0: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
dfb0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
dfc0: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
dfd0: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
dfe0: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
dff0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
e000: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
e010: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
e020: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
e030: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20  re in version 1 
e040: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
e050: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65  s object.  ** de
e060: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65  finition.  Those
e070: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65   that follow are
e080: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f   added in versio
e090: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a  n 2 or later.  *
e0a0: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  /.  int (*xCurre
e0b0: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
e0c0: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
e0d0: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
e0e0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e0f0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e100: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
e110: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
e120: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54  s object..  ** T
e130: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66  hose below are f
e140: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64  or version 3 and
e150: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20   greater..  */. 
e160: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65   int (*xSetSyste
e170: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
e180: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e190: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
e1a0: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20  syscall_ptr);.  
e1b0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
e1c0: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d  ptr (*xGetSystem
e1d0: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
e1e0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e1f0: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20  zName);.  const 
e200: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73  char *(*xNextSys
e210: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
e220: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e230: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a  r *zName);.  /*.
e240: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
e250: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
e260: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68  rsions 1 through
e270: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   3 of the sqlite
e280: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
e290: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
e2a0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
e2b0: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
e2c0: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
e2d0: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
e2e0: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
e2f0: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
e300: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
e310: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
e320: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
e330: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
e340: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
e350: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
e360: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
e370: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
e380: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
e390: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
e3a0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
e3b0: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
e3c0: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
e3d0: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
e3e0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
e3f0: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
e400: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
e410: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
e420: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e430: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
e440: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
e450: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
e460: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
e470: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
e480: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
e490: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
e4a0: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
e4b0: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
e4c0: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
e4d0: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
e4e0: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
e4f0: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
e500: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
e510: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
e520: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
e530: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
e540: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
e550: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
e560: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
e570: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
e580: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
e590: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
e5a0: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
e5b0: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
e5c0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
e5d0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
e5e0: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
e5f0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
e600: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
e610: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
e620: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
e630: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
e640: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
e650: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
e660: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
e670: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
e680: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
e690: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
e6a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
e6b0: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
e6c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
e6d0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
e6e0: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
e6f0: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
e700: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
e710: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
e720: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
e730: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
e740: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
e750: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
e760: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
e770: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
e780: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
e790: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
e7a0: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
e7b0: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
e7c0: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
e7d0: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
e7e0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
e7f0: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
e800: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
e810: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
e820: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
e830: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
e840: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
e850: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
e860: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
e870: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
e880: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
e890: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
e8a0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
e8b0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
e8c0: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
e8d0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
e8e0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
e8f0: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
e900: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
e910: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
e920: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
e930: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
e940: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
e950: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
e960: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
e970: 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f   on the correspo
e980: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
e990: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
e9a0: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
e9b0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
e9c0: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
e9d0: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
e9e0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
e9f0: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
ea00: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
ea10: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
ea20: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
ea30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ea40: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
ea50: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
ea60: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
ea70: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
ea80: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
ea90: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
eaa0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
eab0: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
eac0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
ead0: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
eae0: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
eaf0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
eb00: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
eb10: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
eb20: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
eb30: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
eb40: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
eb50: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
eb60: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
eb70: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
eb80: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
eb90: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
eba0: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
ebb0: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
ebc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
ebd0: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
ebe0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
ebf0: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
ec00: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
ec10: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
ec20: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ec30: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
ec40: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
ec50: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
ec60: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
ec70: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
ec80: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
ec90: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
eca0: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
ecb0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ecc0: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
ecd0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
ece0: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
ecf0: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
ed00: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
ed10: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
ed20: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
ed30: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
ed40: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
ed50: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
ed60: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
ed70: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
ed80: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
ed90: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
eda0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
edb0: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
edc0: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
edd0: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
ede0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
edf0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
ee00: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
ee10: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
ee20: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
ee30: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
ee40: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
ee50: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
ee60: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
ee70: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
ee80: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ee90: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
eea0: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
eeb0: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
eec0: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
eed0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
eee0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
eef0: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
ef00: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
ef10: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
ef20: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
ef30: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
ef40: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
ef50: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
ef60: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ef70: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
ef80: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
ef90: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
efa0: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
efb0: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
efc0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
efd0: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
efe0: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
eff0: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
f000: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
f010: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
f020: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
f030: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
f040: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f050: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
f060: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
f070: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
f080: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
f090: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f0a0: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
f0b0: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
f0c0: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
f0d0: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
f0e0: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
f0f0: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
f100: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
f110: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
f120: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
f130: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
f140: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
f150: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
f160: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
f170: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
f180: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
f190: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
f1a0: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
f1b0: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
f1c0: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
f1d0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
f1e0: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
f1f0: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
f200: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
f210: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
f220: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
f230: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
f240: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
f250: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
f260: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f270: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
f280: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
f290: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
f2a0: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
f2b0: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
f2c0: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
f2d0: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
f2e0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
f2f0: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
f300: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
f310: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
f320: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f330: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
f340: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
f350: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
f360: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
f370: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
f380: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
f390: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
f3a0: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
f3b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f3c0: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
f3d0: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
f3e0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
f3f0: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
f400: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
f410: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
f420: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
f430: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
f440: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
f450: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
f460: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
f470: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
f480: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
f490: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
f4a0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
f4b0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
f4c0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
f4d0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
f4e0: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
f4f0: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
f500: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f510: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
f520: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
f530: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
f540: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
f550: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
f560: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
f570: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
f580: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
f590: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
f5a0: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
f5b0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
f5c0: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
f5d0: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
f5e0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f5f0: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
f600: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
f610: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
f620: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
f630: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
f640: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
f650: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
f660: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
f670: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
f680: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
f690: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
f6a0: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
f6b0: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
f6c0: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
f6d0: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
f6e0: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
f6f0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
f700: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
f710: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
f720: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
f730: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
f740: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
f750: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
f760: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
f770: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f780: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
f790: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
f7a0: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
f7b0: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
f7c0: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
f7d0: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
f7e0: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
f7f0: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
f800: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
f810: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
f820: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
f830: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
f840: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
f850: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
f860: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
f870: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
f880: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
f890: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
f8a0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f8b0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
f8c0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
f8d0: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
f8e0: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
f8f0: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
f900: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
f910: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
f920: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
f930: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
f940: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f950: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
f960: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
f970: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f980: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
f990: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
f9a0: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
f9b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
f9c0: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
f9d0: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
f9e0: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
f9f0: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
fa00: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
fa10: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
fa20: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
fa30: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
fa40: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
fa50: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
fa60: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
fa70: 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
fa80: 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
fa90: 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
faa0: 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
fab0: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
fac0: 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
fad0: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
fae0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
faf0: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
fb00: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
fb10: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
fb20: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
fb30: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
fb40: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
fb50: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
fb60: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
fb70: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
fb80: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
fb90: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
fba0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
fbb0: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
fbc0: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
fbd0: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
fbe0: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
fbf0: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
fc00: 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lure..*/.SQLITE_
fc10: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
fc20: 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
fc30: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
fc40: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fc50: 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  n(void);.SQLITE_
fc60: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
fc70: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53  os_init(void);.S
fc80: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
fc90: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
fca0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
fcb0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
fcc0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
fcd0: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
fce0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
fcf0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
fd00: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
fd10: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
fd20: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
fd30: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
fd40: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
fd50: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
fd60: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
fd70: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
fd80: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
fd90: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
fda0: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
fdb0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
fdc0: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
fdd0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
fde0: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
fdf0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
fe00: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
fe10: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
fe20: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
fe30: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
fe40: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
fe50: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
fe60: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
fe70: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
fe80: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
fe90: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
fea0: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
feb0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
fec0: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
fed0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
fee0: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
fef0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
ff00: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
ff10: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
ff20: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
ff30: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
ff40: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
ff50: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
ff60: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
ff70: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
ff80: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
ff90: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ffa0: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
ffb0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
ffc0: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
ffd0: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
ffe0: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
fff0: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
10000 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
10010 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
10020 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
10030 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
10040 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
10050 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
10060 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
10070 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
10080 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
10090 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
100a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
100b0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
100c0 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
100d0 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
100e0 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
100f0 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
10100 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
10110 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
10120 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
10130 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
10140 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
10150 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
10160 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
10170 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
10180 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
10190 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
101a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
101b0 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
101c0 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
101d0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
101e0 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
101f0 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
10200 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
10210 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
10220 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
10230 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
10240 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
10250 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  e]..*/.SQLITE_AP
10260 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
10270 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
10280 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10290 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
102a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
102b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
102c0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
102d0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
102e0 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72  to make configur
102f0 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
10300 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20   to a [database 
10310 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
10320 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  e interface is s
10330 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71  imilar to.** [sq
10340 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
10350 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20  except that the 
10360 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f  changes apply to
10370 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61   a single.** [da
10380 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10390 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e  n] (specified in
103a0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
103b0 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent)..**.** The 
103c0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
103d0 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
103e0 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69  nfig(D,V,...)  i
103f0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
10400 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
10410 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  IDE | configurat
10420 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69  ion verb] - an i
10430 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20  nteger code .** 
10440 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77  that indicates w
10450 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68  hat aspect of th
10460 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
10470 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
10480 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
10490 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
104a0 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64  ents vary depend
104b0 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69  ing on the confi
104c0 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a  guration verb..*
104d0 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  *.** ^Calls to s
104e0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
104f0 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
10500 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  _OK if and only 
10510 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69  if.** the call i
10520 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63  s considered suc
10530 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  cessful..*/.SQLI
10540 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
10550 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
10560 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
10570 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
10580 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
10590 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
105a0 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
105b0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
105c0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
105d0 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
105e0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
105f0 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
10600 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
10610 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
10620 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
10630 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
10640 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
10650 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
10660 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
10670 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
10680 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
10690 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
106a0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
106b0 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
106c0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
106d0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
106e0 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
106f0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
10700 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
10710 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
10720 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
10730 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
10740 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
10750 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
10760 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
10770 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
10780 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
10790 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
107a0 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
107b0 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
107c0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
107d0 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
107e0 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
107f0 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
10800 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
10810 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
10820 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
10830 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
10840 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10850 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
10860 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
10870 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
10880 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
10890 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
108a0 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
108b0 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
108c0 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
108d0 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
108e0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
108f0 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
10900 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10910 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
10920 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
10930 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
10940 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
10950 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
10960 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
10970 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
10980 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
10990 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
109a0 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
109b0 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
109c0 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
109d0 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
109e0 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
109f0 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
10a00 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
10a10 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61  he xMalloc, xRea
10a20 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20  lloc, and xFree 
10a30 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
10a40 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
10a50 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
10a60 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
10a70 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
10a80 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
10a90 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  ry..** ^SQLite g
10aa0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
10ab0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10ac0 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
10ad0 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
10ae0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
10af0 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
10b00 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20  xRoundup..**.** 
10b10 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
10b20 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
10b30 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
10b40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
10b50 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
10b60 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
10b70 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
10b80 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
10b90 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
10ba0 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
10bb0 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
10bc0 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
10bd0 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
10be0 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
10bf0 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
10c00 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
10c10 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
10c20 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
10c30 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
10c40 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
10c50 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
10c60 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
10c70 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
10c80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
10c90 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
10ca0 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
10cb0 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
10cc0 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
10cd0 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
10ce0 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
10cf0 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
10d00 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
10d10 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
10d20 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
10d30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
10d40 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
10d50 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
10d60 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
10d70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
10d80 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
10d90 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
10da0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
10db0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
10dc0 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
10dd0 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
10de0 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
10df0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
10e00 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a   For example,.**
10e10 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
10e20 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
10e30 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
10e40 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
10e50 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
10e60 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
10e70 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
10e80 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
10e90 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
10ea0 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
10eb0 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
10ec0 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
10ed0 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
10ee0 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
10ef0 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
10f00 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
10f10 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
10f20 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
10f30 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
10f40 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
10f50 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
10f60 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
10f70 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
10f80 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
10f90 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
10fa0 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
10fb0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
10fc0 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
10fd0 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
10fe0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
10ff0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
11000 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
11010 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
11020 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
11030 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
11040 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
11050 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
11060 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
11070 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
11080 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
11090 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
110a0 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
110b0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
110c0 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
110d0 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
110e0 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
110f0 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
11100 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
11110 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
11120 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
11130 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
11140 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
11150 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
11160 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
11170 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
11180 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
11190 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
111a0 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
111b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
111c0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
111d0 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
111e0 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
111f0 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
11200 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
11210 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
11220 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
11230 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
11240 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
11250 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
11260 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
11270 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
11280 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
11290 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
112a0 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
112b0 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
112c0 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
112d0 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
112e0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
112f0 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
11300 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
11310 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
11320 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
11330 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
11340 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
11350 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
11360 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
11370 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
11380 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
11390 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
113a0 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
113b0 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
113c0 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
113d0 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
113e0 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
113f0 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
11400 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
11410 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
11420 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
11430 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
11440 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11450 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
11460 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
11470 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
11480 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
11490 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
114a0 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
114b0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
114c0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
114d0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
114e0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
114f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
11500 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
11510 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
11520 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11530 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
11540 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
11550 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11560 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
11570 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
11580 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
11590 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
115a0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
115b0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
115c0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
115d0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
115e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
115f0 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
11600 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
11610 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
11620 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
11630 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
11640 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11650 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
11660 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
11670 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
11680 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
11690 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
116a0 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
116b0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
116c0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
116d0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
116e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
116f0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
11700 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
11710 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11720 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
11730 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11740 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
11750 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
11760 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
11770 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
11780 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
11790 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
117a0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
117b0 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
117c0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
117d0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
117e0 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
117f0 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
11800 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
11810 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
11820 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
11830 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
11840 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11850 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
11860 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
11870 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
11880 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
11890 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
118a0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
118b0 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
118c0 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
118d0 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
118e0 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
118f0 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
11900 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
11910 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
11920 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
11930 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
11940 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
11950 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
11960 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
11970 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11980 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
11990 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
119a0 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
119b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
119c0 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
119d0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
119e0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
119f0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
11a00 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
11a10 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
11a20 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
11a30 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
11a40 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
11a50 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
11a60 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
11a70 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
11a80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11a90 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
11aa0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
11ab0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
11ac0 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
11ad0 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
11ae0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11af0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
11b00 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
11b10 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
11b20 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
11b30 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
11b40 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
11b50 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
11b60 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
11b70 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
11b80 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
11b90 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
11ba0 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
11bb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11bc0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
11bd0 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
11be0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
11bf0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
11c00 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
11c10 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
11c20 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
11c30 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
11c40 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
11c50 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
11c60 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
11c70 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
11c80 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11c90 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
11ca0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
11cb0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
11cc0 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
11cd0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
11ce0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11cf0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
11d00 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
11d10 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
11d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
11d30 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
11d40 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
11d50 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
11d60 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
11d70 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11d80 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11d90 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
11da0 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
11db0 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
11dc0 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
11dd0 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
11de0 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
11df0 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
11e00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11e10 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
11e20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
11e30 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
11e40 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
11e50 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
11e60 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
11e70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
11e80 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11e90 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
11ea0 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
11eb0 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
11ec0 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
11ed0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
11ee0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
11ef0 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
11f00 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
11f10 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
11f20 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
11f30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11f40 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
11f50 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
11f60 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
11f70 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
11f80 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
11f90 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
11fa0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
11fb0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
11fc0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
11fd0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
11fe0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
11ff0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
12000 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
12010 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
12020 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
12030 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
12040 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
12050 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
12060 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
12070 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
12080 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
12090 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
120a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
120b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
120c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
120d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
120e0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
120f0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
12100 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12110 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
12120 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
12130 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
12140 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
12150 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
12160 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
12170 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
12180 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
12190 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
121a0 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
121b0 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
121c0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
121d0 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
121e0 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
121f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12200 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
12210 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
12220 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
12230 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
12240 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
12250 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t 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 0a 2a 2a 20 62 65 66 6f  tructure.** befo
12280 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
12290 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
122a0 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
122b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
122c0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
122d0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
122e0 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
122f0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
12300 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
12310 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
12320 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12330 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
12340 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12350 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
12360 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12370 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12380 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
12390 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
123a0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
123b0 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
123c0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
123d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
123e0 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
123f0 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
12400 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
12410 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
12420 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
12430 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
12440 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
12450 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
12460 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12470 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
12480 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
12490 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
124a0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
124b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
124c0 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
124d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
124e0 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
124f0 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
12500 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
12510 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
12520 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
12530 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74  type int,.** int
12540 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
12550 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
12560 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
12570 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
12580 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  of.** memory all
12590 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
125a0 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
125b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
125c0 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64  tistics are.** d
125d0 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c  isabled, the fol
125e0 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
125f0 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
12600 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
12610 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
12620 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
12630 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
12640 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
12650 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
12660 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
12670 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
12680 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
12690 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
126a0 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tatus()].**   </
126b0 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
126c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
126d0 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
126e0 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
126f0 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
12700 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
12710 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
12720 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
12730 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
12740 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
12750 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
12760 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
12770 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
12780 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12790 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
127a0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
127b0 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
127c0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
127d0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f  CONFIG_SCRATCH o
127e0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
127f0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
12800 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53  buffer.** that S
12810 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
12820 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  r scratch memory
12830 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74  .  ^(There are t
12840 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a  hree arguments.*
12850 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  * to SQLITE_CONF
12860 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70  IG_SCRATCH:  A p
12870 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
12880 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
12890 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
128a0 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
128b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
128c0 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
128d0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
128e0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
128f0 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
12900 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
12910 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
12920 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e  locations (N).)^
12930 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
12940 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
12950 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
12960 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
12970 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
12980 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
12990 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
129a0 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73  Lite will not us
129b0 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  e more than one 
129c0 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
129d0 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e  per thread..** ^
129e0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
129f0 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61  r request a scra
12a00 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
12a10 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
12a20 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
12a30 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a  base page size..
12a40 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  ** ^If SQLite ne
12a50 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
12a60 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
12a70 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
12a80 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
12a90 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
12aa0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
12ab0 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
12ac0 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
12ad0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
12ae0 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
12af0 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74  d.<p>.** ^When t
12b00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70  he application p
12b10 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75  rovides any amou
12b20 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65  nt of scratch me
12b30 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51  mory using.** SQ
12b40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
12b50 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69  TCH, SQLite avoi
12b60 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c  ds unnecessary l
12b70 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  arge.** [sqlite3
12b80 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c  _malloc|heap all
12b90 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  ocations]..** Th
12ba0 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62  is can help [Rob
12bb0 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e  son proof|preven
12bc0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
12bd0 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75  ion failures] du
12be0 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61  e to heap.** fra
12bf0 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f  gmentation in lo
12c00 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65  w-memory embedde
12c10 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f  d systems..** </
12c20 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12c30 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
12c40 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
12c50 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
12c60 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
12c70 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12c80 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69  G_PAGECACHE opti
12c90 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
12ca0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
12cb0 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  fer.** that SQLi
12cc0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74  te can use for t
12cd0 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
12ce0 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
12cf0 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20  default page.** 
12d00 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
12d10 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
12d20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68  configuration sh
12d30 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
12d40 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
12d50 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
12d60 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
12d70 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
12d80 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
12d90 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
12da0 32 5d 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  2].** configurat
12db0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e  ion option..** ^
12dc0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
12dd0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
12de0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
12df0 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20  ACHE: A pointer 
12e00 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69  to.** 8-byte ali
12e10 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  gned.** memory, 
12e20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
12e30 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
12e40 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
12e50 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
12e60 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
12e70 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
12e80 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
12e90 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
12ea0 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
12eb0 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
12ec0 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75  2 and 65536) plu
12ed0 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74  s some extra byt
12ee0 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  es for each.** p
12ef0 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
12f00 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
12f10 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62  a bytes needed b
12f20 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65  y the page heade
12f30 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  r.** can be dete
12f40 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  rmined using the
12f50 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12f60 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70  PCACHE_HDRSZ] op
12f70 74 69 6f 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c  tion .** to [sql
12f80 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
12f90 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  ** ^It is harmle
12fa0 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
12fb0 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
12fc0 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20  ,.** for the sz 
12fd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
12fe0 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65  larger than nece
12ff0 73 73 61 72 79 2e 20 20 54 68 65 20 66 69 72 73  ssary.  The firs
13000 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
13010 6f 75 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  ould pointer to 
13020 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
13030 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  d block of memor
13040 79 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 74 20  y that.** is at 
13050 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
13060 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65   of memory, othe
13070 72 77 69 73 65 20 73 75 62 73 65 71 75 65 6e 74  rwise subsequent
13080 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
13090 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53  undefined..** ^S
130a0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
130b0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
130c0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
130d0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
130e0 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
130f0 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
13100 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
13110 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
13120 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
13130 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
13140 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
13150 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
13160 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
13170 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
13180 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
13190 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
131a0 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
131b0 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
131c0 20 73 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a   space.</dd>.**.
131d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
131e0 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
131f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
13200 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
13210 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13220 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65  _HEAP option spe
13230 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
13240 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a  memory buffer .*
13250 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  * that SQLite wi
13260 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  ll use for all o
13270 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
13280 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13290 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20  needs.** beyond 
132a0 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66  those provided f
132b0 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
132c0 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
132d0 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  d.** [SQLITE_CON
132e0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
132f0 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  ** ^The SQLITE_C
13300 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f  ONFIG_HEAP optio
13310 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
13320 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
13330 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
13340 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  h either [SQLITE
13350 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
13360 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42   or [SQLITE_ENAB
13370 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20  LE_MEMSYS5] and 
13380 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
13390 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76  TE_ERROR] if inv
133a0 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  oked otherwise..
133b0 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
133c0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
133d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
133e0 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74  EAP:.** An 8-byt
133f0 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
13400 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
13410 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
13420 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
13430 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
13440 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
13450 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
13460 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
13470 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
13480 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
13490 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
134a0 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
134b0 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
134c0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
134d0 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
134e0 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
134f0 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
13500 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
13510 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
13520 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
13530 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
13540 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
13550 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
13560 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
13570 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
13580 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
13590 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
135a0 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
135b0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
135c0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
135d0 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
135e0 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
135f0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
13600 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
13610 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
13620 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
13630 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
13640 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
13650 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
13660 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
13670 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
13680 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
13690 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
136a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
136b0 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
136c0 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
136d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
136e0 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
136f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
13700 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
13710 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
13720 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  IG_MUTEX option 
13730 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13740 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
13750 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
13760 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
13770 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
13780 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
13790 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
137a0 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
137b0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
137c0 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
137d0 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
137e0 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65  .** in place the
137f0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
13800 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
13810 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
13820 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  kes a copy of.**
13830 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
13840 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
13850 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
13860 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
13870 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
13880 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
13890 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
138a0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
138b0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
138c0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
138d0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
138e0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
138f0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
13900 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
13910 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
13920 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
13930 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
13940 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
13950 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13960 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
13970 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
13980 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13990 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
139a0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
139b0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
139c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
139d0 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
139e0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
139f0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
13a00 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
13a10 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70  NFIG_GETMUTEX op
13a20 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
13a30 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
13a40 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
13a50 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
13a60 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
13a70 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
13a80 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
13a90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
13aa0 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
13ab0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
13ac0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
13ad0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
13ae0 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
13af0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
13b00 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
13b10 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
13b20 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
13b30 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
13b40 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
13b50 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
13b60 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
13b70 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
13b80 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
13b90 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
13ba0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
13bb0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
13bc0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
13bd0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
13be0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
13bf0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
13c00 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
13c10 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
13c20 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
13c30 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
13c40 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
13c50 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
13c60 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
13c70 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
13c80 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
13c90 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
13ca0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
13cb0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
13cc0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13cd0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
13ce0 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
13cf0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
13d00 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
13d10 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
13d20 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74  IG_LOOKASIDE opt
13d30 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
13d40 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
13d50 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65  ermine.** the de
13d60 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f  fault size of lo
13d70 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f  okaside memory o
13d80 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65  n each [database
13d90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
13da0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
13db0 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
13dc0 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
13dd0 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
13de0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
13df0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
13e00 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
13e10 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
13e20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
13e30 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e  )^  ^(SQLITE_CON
13e40 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a  FIG_LOOKASIDE.**
13e50 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66   sets the <i>def
13e60 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
13e70 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
13e80 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
13e90 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69  OKASIDE].** opti
13ea0 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  on to [sqlite3_d
13eb0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
13ec0 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
13ed0 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
13ee0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
13ef0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
13f00 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
13f10 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13f20 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13f30 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
13f40 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
13f50 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
13f60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
13f70 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
13f80 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
13f90 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
13fa0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
13fb0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
13fc0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
13fd0 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
13fe0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
13ff0 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
14000 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
14010 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
14020 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65  on.)^.** ^SQLite
14030 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
14040 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63   the [sqlite3_pc
14050 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
14060 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bject.</dd>.**.*
14070 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14080 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c  G_GETPCACHE2]] <
14090 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
140a0 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e  _GETPCACHE2</dt>
140b0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
140c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
140d0 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
140e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
140f0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
14100 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14110 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
14120 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14130 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
14140 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75  ies of.** the cu
14150 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65  rrent page cache
14160 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
14170 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
14180 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
14190 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
141a0 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
141b0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
141c0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
141d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
141e0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
141f0 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53   configure the S
14200 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20  QLite.** global 
14210 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20  [error log]..** 
14220 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  (^The SQLITE_CON
14230 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
14240 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
14250 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
14260 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
14270 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
14280 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
14290 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
142a0 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
142b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
142c0 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
142d0 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
142e0 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
142f0 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
14300 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
14310 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
14320 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
14330 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
14340 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
14350 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
14360 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
14370 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
14380 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
14390 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
143a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
143b0 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
143c0 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
143d0 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
143e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
143f0 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
14400 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
14410 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
14420 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
14430 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
14440 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
14450 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
14460 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
14470 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
14480 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
14490 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
144a0 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
144b0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
144c0 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
144d0 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
144e0 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
144f0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
14500 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
14510 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
14520 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
14530 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
14540 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
14550 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
14560 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
14570 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
14580 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
14590 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
145a0 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
145b0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
145c0 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
145d0 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
145e0 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
145f0 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
14600 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
14610 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
14620 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14630 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
14640 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
14650 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
14660 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14670 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
14680 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14690 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e  FIG_URI.** <dd>^
146a0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
146b0 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61  IG_URI option ta
146c0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
146d0 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
146e0 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72  t..** If non-zer
146f0 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
14700 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
14710 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
14720 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
14730 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20  ro,.** then URI 
14740 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
14750 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
14760 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
14770 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
14780 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
14790 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74  lenames passed t
147a0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
147b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
147c0 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  n_v2()],.** [sql
147d0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
147e0 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
147f0 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
14800 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
14810 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
14820 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
14830 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
14840 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
14850 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
14860 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
14870 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
14880 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
14890 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
148a0 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
148b0 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
148c0 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
148d0 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
148e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
148f0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
14900 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
14910 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
14920 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
14930 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
14940 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
14950 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
14960 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
14970 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
14980 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
14990 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
149a0 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
149b0 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
149c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
149d0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
149e0 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
149f0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
14a00 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
14a10 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
14a20 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
14a30 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74  EX_SCAN option t
14a40 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
14a50 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  teger.** argumen
14a60 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72  t which is inter
14a70 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
14a80 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
14a90 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
14aa0 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  e.** the use of 
14ab0 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
14ac0 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
14ad0 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
14ae0 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a  ry optimizer..**
14af0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
14b00 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
14b10 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
14b20 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
14b30 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
14b40 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
14b50 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
14b60 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
14b70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
14b80 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
14b90 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
14ba0 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
14bb0 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
14bc0 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
14bd0 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
14be0 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
14bf0 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
14c00 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
14c10 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
14c20 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70  n.** when the op
14c30 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
14c40 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
14c50 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
14c60 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
14c70 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
14c80 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
14c90 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
14ca0 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
14cb0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
14cc0 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
14cd0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
14ce0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
14cf0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14d00 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
14d10 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
14d20 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
14d30 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
14d40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14d50 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
14d60 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
14d70 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
14d80 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
14d90 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
14da0 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
14db0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
14dc0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
14dd0 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
14de0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
14df0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14e00 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
14e10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14e20 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
14e30 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
14e40 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
14e50 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
14e60 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
14e70 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
14e80 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOG] pre-process
14e90 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
14ea0 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
14eb0 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
14ec0 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
14ed0 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
14ee0 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
14ef0 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
14f00 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
14f10 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
14f20 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
14f30 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
14f40 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
14f50 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
14f60 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
14f70 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
14f80 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
14f90 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
14fa0 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
14fb0 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
14fc0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
14fd0 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
14fe0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
14ff0 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
15000 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
15010 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
15020 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
15030 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
15040 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
15050 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
15060 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
15070 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
15080 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
15090 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
150a0 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
150b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
150c0 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
150d0 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
150e0 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
150f0 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
15100 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
15110 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
15120 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
15130 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
15140 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
15150 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
15160 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
15170 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
15180 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
15190 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41  In this case.  A
151a0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69  n example of usi
151b0 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  ng this.** confi
151c0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
151d0 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74  can be seen in t
151e0 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e  he "test_sqllog.
151f0 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69  c" source file i
15200 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63  n.** the canonic
15210 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  al SQLite source
15220 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   tree.</dd>.**.*
15230 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15240 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  G_MMAP_SIZE]].**
15250 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15260 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20  IG_MMAP_SIZE.** 
15270 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  <dd>^SQLITE_CONF
15280 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b  IG_MMAP_SIZE tak
15290 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e  es two 64-bit in
152a0 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69  teger (sqlite3_i
152b0 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20  nt64) values.** 
152c0 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66  that are the def
152d0 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c  ault mmap size l
152e0 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c  imit (the defaul
152f0 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a  t setting for.**
15300 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
15310 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78  ze]) and the max
15320 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
15330 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a  p size limit..**
15340 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
15350 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
15360 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
15370 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15380 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
15390 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
153a0 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61  mmap_size] comma
153b0 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20  nd, or by using 
153c0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
153d0 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
153e0 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e  file control.  ^
153f0 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c  (The maximum all
15400 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
15410 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74  * will be silent
15420 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20  ly truncated if 
15430 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61  necessary so tha
15440 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  t it does not ex
15450 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ceed the.** comp
15460 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
15470 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
15480 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
15490 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
154a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
154b0 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69  ion.)^.** ^If ei
154c0 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f  ther argument to
154d0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
154e0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
154f0 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  hat argument is.
15500 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74  ** changed to it
15510 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64  s compile-time d
15520 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efault..**.** [[
15530 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
15540 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a  N32_HEAPSIZE]].*
15550 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15560 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
15570 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  ZE.** <dd>^The S
15580 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
15590 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69  32_HEAPSIZE opti
155a0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
155b0 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
155c0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f  s.** compiled fo
155d0 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74  r Windows with t
155e0 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32  he [SQLITE_WIN32
155f0 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f  _MALLOC] pre-pro
15600 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20  cessor macro.** 
15610 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45  defined. ^SQLITE
15620 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15630 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
15640 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
15650 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
15660 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
15670 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
15680 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
15690 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  eap..** </dl>.**
156a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
156b0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
156c0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
156d0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
156e0 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  DRSZ.** <dd>^The
156f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15700 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69  CACHE_HDRSZ opti
15710 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
15720 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
15730 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
15740 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
15750 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20  and writes into 
15760 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65  that integer the
15770 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
15780 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61  .** bytes per pa
15790 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  ge required for 
157a0 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51  each page in [SQ
157b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
157c0 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61  CACHE]..** The a
157d0 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73  mount of extra s
157e0 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61  pace required ca
157f0 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69  n change dependi
15800 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ng on the compil
15810 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c  er,.** target pl
15820 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69  atform, and SQLi
15830 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  te version..**.*
15840 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15850 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  G_PMASZ]].** <dt
15860 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
15870 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  MASZ.** <dd>^The
15880 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15890 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  MASZ option take
158a0 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
158b0 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
158c0 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74   an unsigned int
158d0 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68  eger and sets th
158e0 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  e "Minimum PMA S
158f0 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c  ize" for the mul
15900 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f  tithreaded.** so
15910 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74  rter to that int
15920 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75  eger.  The defau
15930 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  lt minimum PMA S
15940 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68  ize is set by th
15950 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52  e.** [SQLITE_SOR
15960 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69  TER_PMASZ] compi
15970 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20  le-time option. 
15980 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65   New threads are
15990 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20   launched.** to 
159a0 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f  help with sort o
159b0 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d  perations when m
159c0 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72  ultithreaded sor
159d0 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c  ting.** is enabl
159e0 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50  ed (using the [P
159f0 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63  RAGMA threads] c
15a00 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20  ommand) and the 
15a10 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e  amount of conten
15a20 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65  t.** to be sorte
15a30 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61  d exceeds the pa
15a40 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68  ge size times th
15a50 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65  e minimum of the
15a60 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68  .** [PRAGMA cach
15a70 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20  e_size] setting 
15a80 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a  and this value..
15a90 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
15aa0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15ab0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
15ac0 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
15ad0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15ae0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
15af0 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
15b00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15b10 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
15b20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
15b30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15b40 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
15b50 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
15b60 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
15b70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15b80 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
15b90 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
15ba0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
15bb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15bc0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
15bd0 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
15be0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
15bf0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
15c00 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
15c10 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
15c20 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
15c30 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
15c40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
15c50 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
15c60 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
15c70 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
15c80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15c90 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
15ca0 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
15cb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15cc0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
15cd0 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
15ce0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
15cf0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
15d00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15d10 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
15d20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
15d30 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
15d40 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
15d50 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
15d60 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
15d70 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
15d80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15d90 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
15da0 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
15db0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15dc0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
15dd0 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
15de0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
15df0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15e00 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
15e10 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
15e20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15e30 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
15e40 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
15e50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15e60 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
15e70 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
15e80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15e90 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15ea0 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
15eb0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
15ec0 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
15ed0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15ee0 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
15ef0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
15f00 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
15f10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15f20 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
15f30 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a  NDEX_SCAN 20  /*
15f40 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
15f50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
15f60 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f  LLOG       21  /
15f70 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a  * xSqllog, void*
15f80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15f90 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
15fa0 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71  IZE    22  /* sq
15fb0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c  lite3_int64, sql
15fc0 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64  ite3_int64 */.#d
15fd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15fe0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
15ff0 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69  ZE      23  /* i
16000 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66  nt nByte */.#def
16010 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16020 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20  G_PCACHE_HDRSZ  
16030 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74        24  /* int
16040 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65   *psz */.#define
16050 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16060 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20  MASZ            
16070 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e     25  /* unsign
16080 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a  ed int szPma */.
16090 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
160a0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
160b0 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
160c0 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
160d0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
160e0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
160f0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
16100 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
16110 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
16120 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
16130 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
16140 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
16150 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
16160 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
16170 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16180 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
16190 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
161a0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
161b0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
161c0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
161d0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
161e0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
161f0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
16200 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
16210 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
16220 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
16230 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
16240 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
16250 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
16260 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
16270 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
16280 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
16290 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
162a0 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
162b0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
162c0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
162d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
162e0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
162f0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
16300 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
16310 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
16320 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
16330 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
16340 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
16350 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
16360 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
16370 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
16380 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
16390 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
163a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
163b0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
163c0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
163d0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
163e0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
163f0 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
16400 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
16410 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
16420 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
16430 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
16440 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
16450 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
16460 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
16470 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
16480 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
16490 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
164a0 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
164b0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
164c0 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
164d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
164e0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
164f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
16500 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
16510 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
16520 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
16530 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
16540 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
16550 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
16560 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
16570 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
16580 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
16590 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
165a0 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
165b0 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
165c0 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
165d0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
165e0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
165f0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
16600 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
16610 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
16620 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
16630 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
16640 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
16650 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
16660 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
16670 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
16680 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
16690 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
166a0 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
166b0 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
166c0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
166d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
166e0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
166f0 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
16700 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
16710 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
16720 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
16730 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
16740 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
16750 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
16760 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
16770 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
16780 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
16790 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
167a0 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
167b0 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
167c0 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
167d0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
167e0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
167f0 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
16800 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
16810 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
16820 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
16830 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
16840 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
16850 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
16860 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
16870 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
16880 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
16890 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
168a0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
168b0 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
168c0 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
168d0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
168e0 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
168f0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
16900 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
16910 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
16920 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
16930 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
16940 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
16950 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
16960 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
16970 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
16980 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
16990 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
169a0 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
169b0 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
169c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
169d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
169e0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
169f0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
16a00 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
16a10 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
16a20 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
16a30 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
16a40 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
16a50 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
16a60 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
16a70 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
16a80 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
16a90 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
16aa0 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
16ab0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
16ac0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
16ad0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
16ae0 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
16af0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
16b00 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
16b10 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
16b20 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
16b30 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
16b40 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
16b50 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
16b60 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
16b70 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
16b80 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
16b90 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
16ba0 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
16bb0 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
16bc0 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72  o enable trigger
16bd0 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
16be0 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
16bf0 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
16c00 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
16c10 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
16c20 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
16c30 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
16c40 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
16c50 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
16c60 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72  ther triggers ar
16c70 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  e disabled or en
16c80 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
16c90 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
16ca0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16cb0 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
16cc0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
16cd0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
16ce0 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20  trigger setting 
16cf0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
16d00 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
16d10 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
16d20 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
16d30 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
16d40 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
16d50 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
16d60 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
16d70 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
16d80 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e       1002  /* in
16d90 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
16da0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
16db0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
16dc0 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69    1003  /* int i
16dd0 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
16de0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
16df0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
16e00 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
16e10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
16e20 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
16e30 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
16e40 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
16e50 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
16e60 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
16e70 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
16e80 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
16e90 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
16ea0 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
16eb0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
16ec0 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
16ed0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
16ee0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
16ef0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
16f00 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
16f10 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
16f20 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
16f30 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
16f40 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61   Rowid.**.** ^Ea
16f50 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
16f60 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
16f70 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
16f80 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
16f90 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
16fa0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
16fb0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
16fc0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
16fd0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
16fe0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
16ff0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
17000 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
17010 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
17020 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
17030 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
17040 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
17050 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
17060 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
17070 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
17080 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
17090 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
170a0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
170b0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
170c0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
170d0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
170e0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
170f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
17100 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
17110 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
17120 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
17130 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
17140 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
17150 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
17160 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
17170 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
17180 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
17190 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
171a0 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
171b0 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
171c0 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
171d0 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
171e0 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
171f0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
17200 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
17210 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
17220 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
17230 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17240 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
17250 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
17260 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
17270 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
17280 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
17290 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
172a0 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
172b0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
172c0 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
172d0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
172e0 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
172f0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
17300 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
17310 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
17320 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
17330 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
17340 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
17350 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
17360 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
17370 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
17380 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17390 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
173a0 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
173b0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
173c0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
173d0 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
173e0 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
173f0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
17400 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
17410 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
17420 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
17430 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
17440 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
17450 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
17460 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
17470 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
17480 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
17490 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
174a0 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
174b0 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
174c0 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
174d0 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
174e0 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
174f0 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
17500 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
17510 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
17520 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
17530 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
17540 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
17550 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
17560 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
17570 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
17580 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
17590 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
175a0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
175b0 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
175c0 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
175d0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
175e0 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
175f0 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
17600 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
17610 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
17620 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
17630 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
17640 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
17650 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
17660 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
17670 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
17680 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
17690 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
176a0 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
176b0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
176c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
176d0 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
176e0 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
176f0 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
17700 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
17710 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
17720 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
17730 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
17740 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
17750 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
17760 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
17770 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
17780 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
17790 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
177a0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
177b0 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
177c0 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
177d0 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
177e0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
177f0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
17800 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17810 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
17820 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
17830 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
17840 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
17850 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
17860 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
17870 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
17880 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
17890 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
178a0 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
178b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
178c0 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
178d0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
178e0 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
178f0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
17900 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
17910 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65  s modified, inse
17920 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  rted or.** delet
17930 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
17940 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
17950 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
17960 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
17970 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64  atement on the d
17980 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17990 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
179a0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
179b0 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e  er..** ^Executin
179c0 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
179d0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
179e0 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66  t does not modif
179f0 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  y the value.** r
17a00 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
17a10 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
17a20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61  ^Only changes ma
17a30 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74  de directly by t
17a40 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  he INSERT, UPDAT
17a50 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
17a60 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e  ement are.** con
17a70 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69  sidered - auxili
17a80 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
17a90 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52  ed by [CREATE TR
17aa0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
17ab0 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20  ], .** [foreign 
17ac0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20  key actions] or 
17ad0 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
17ae0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
17af0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
17b00 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20  .** .** Changes 
17b10 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
17b20 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
17b30 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f  y .** [INSTEAD O
17b40 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54  F trigger | INST
17b50 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d  EAD OF triggers]
17b60 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
17b70 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a  . ^The value .**
17b80 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
17b90 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
17ba0 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
17bb0 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
17bc0 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45  TE or .** DELETE
17bd0 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f   statement run o
17be0 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61  n a view is alwa
17bf0 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68  ys zero. Only ch
17c00 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65  anges made to re
17c10 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72  al .** tables ar
17c20 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
17c30 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65   Things are more
17c40 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20   complicated if 
17c50 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
17c60 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
17c70 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68  s.** executed wh
17c80 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72  ile a trigger pr
17c90 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67  ogram is running
17ca0 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65  . This may happe
17cb0 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67  n if the.** prog
17cc0 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68  ram uses the [ch
17cd0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
17ce0 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d  tion], or if som
17cf0 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b  e other callback
17d00 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76  .** function inv
17d10 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61  okes sqlite3_cha
17d20 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e  nges() directly.
17d30 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a   Essentially:.**
17d40 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c   .** <ul>.**   <
17d50 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74  li> ^(Before ent
17d60 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20  ering a trigger 
17d70 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75  program the valu
17d80 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
17d90 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
17da0 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
17db0 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74  on is saved. Aft
17dc0 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70  er the trigger p
17dd0 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20  rogram .**      
17de0 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20    has finished, 
17df0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c  the original val
17e00 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29  ue is restored.)
17e10 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ^.** .**   <li> 
17e20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67  ^(Within a trigg
17e30 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20  er program each 
17e40 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61  INSERT, UPDATE a
17e50 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20  nd DELETE .**   
17e60 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73       statement s
17e70 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65  ets the value re
17e80 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
17e90 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
17ea0 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70         upon comp
17eb0 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c  letion as normal
17ec0 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69  . Of course, thi
17ed0 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74  s value will not
17ee0 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20   include .**    
17ef0 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20      any changes 
17f00 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62  performed by sub
17f10 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68  -triggers, as th
17f20 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
17f30 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76  s() .**        v
17f40 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76  alue will be sav
17f50 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20  ed and restored 
17f60 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74  after each sub-t
17f70 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29  rigger has run.)
17f80 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a  ^.** </ul>.** .*
17f90 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68  * ^This means th
17fa0 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65  at if the change
17fb0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
17fc0 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73   (or similar) is
17fd0 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20   used.** by the 
17fe0 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50  first INSERT, UP
17ff0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
18000 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
18010 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a  a trigger, it .*
18020 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  * returns the va
18030 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20  lue as set when 
18040 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74  the calling stat
18050 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63  ement began exec
18060 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74  uting..** ^If it
18070 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
18080 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71  second or subseq
18090 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d  uent such statem
180a0 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
180b0 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d  gger .** program
180c0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
180d0 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68  rned reflects th
180e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
180f0 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65   modified by the
18100 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e   .** previous IN
18110 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
18120 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
18130 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
18140 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   trigger..**.** 
18150 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
18160 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
18170 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
18180 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
18190 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
181a0 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
181b0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
181c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
181d0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
181e0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
181f0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
18200 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
18210 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
18220 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
18230 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
18240 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
18250 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
18260 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
18270 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
18280 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  I int sqlite3_ch
18290 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
182a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
182b0 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
182c0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
182d0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
182e0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
182f0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
18300 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20   rows inserted, 
18310 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64  modified or.** d
18320 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49  eleted by all [I
18330 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
18340 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
18350 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65  tements complete
18360 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64  d.** since the d
18370 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18380 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69  on was opened, i
18390 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65  ncluding those e
183a0 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61  xecuted as.** pa
183b0 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72  rt of trigger pr
183c0 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69  ograms. ^Executi
183d0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
183e0 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
183f0 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61  nt.** does not a
18400 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20  ffect the value 
18410 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
18420 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
18430 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61  s()..** .** ^Cha
18440 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72  nges made as par
18450 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65  t of [foreign ke
18460 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69  y actions] are i
18470 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a  ncluded in the.*
18480 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f  * count, but tho
18490 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  se made as part 
184a0 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
184b0 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
184c0 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68   are.** not. ^Ch
184d0 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
184e0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
184f0 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20  pted by INSTEAD 
18500 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20  OF triggers .** 
18510 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
18520 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  .** .** See also
18530 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
18540 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
18550 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
18560 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
18570 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
18580 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
18590 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
185a0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
185b0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
185c0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
185d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
185e0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
185f0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
18600 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
18610 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
18620 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
18630 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
18640 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
18650 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
18660 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
18670 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
18680 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
18690 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
186a0 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
186b0 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  uery.**.** ^This
186c0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
186d0 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
186e0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
186f0 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
18700 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
18710 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
18720 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
18730 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
18740 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
18750 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
18760 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
18770 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
18780 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
18790 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
187a0 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
187b0 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
187c0 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
187d0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
187e0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
187f0 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
18800 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
18810 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
18820 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
18830 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
18840 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
18850 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
18860 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
18870 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
18880 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
18890 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
188a0 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
188b0 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
188c0 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
188d0 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
188e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
188f0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
18900 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
18910 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
18920 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
18930 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
18940 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
18950 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
18960 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
18970 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
18980 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
18990 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
189a0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
189b0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
189c0 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
189d0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
189e0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
189f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
18a00 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
18a10 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
18a20 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
18a30 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
18a40 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
18a50 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
18a60 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
18a70 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
18a80 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
18a90 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
18aa0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
18ab0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18ac0 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
18ad0 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
18ae0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
18af0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
18b00 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
18b10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
18b20 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
18b30 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
18b40 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
18b50 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
18b60 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18b70 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
18b80 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
18b90 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
18ba0 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
18bb0 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
18bc0 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
18bd0 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
18be0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
18bf0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
18c00 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
18c10 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
18c20 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
18c30 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
18c40 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
18c50 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
18c60 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
18c70 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
18c80 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
18c90 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
18ca0 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
18cb0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
18cc0 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
18cd0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
18ce0 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
18cf0 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
18d00 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
18d10 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
18d20 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
18d30 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18d40 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
18d50 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
18d60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18d70 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
18d80 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
18d90 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
18da0 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
18db0 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
18dc0 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49   happen..*/.SQLI
18dd0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
18de0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
18df0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
18e00 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
18e10 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
18e20 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
18e30 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
18e40 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
18e50 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
18e60 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
18e70 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
18e80 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
18e90 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
18ea0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
18eb0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
18ec0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
18ed0 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
18ee0 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
18ef0 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
18f00 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
18f10 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
18f20 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
18f30 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
18f40 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
18f50 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
18f60 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
18f70 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
18f80 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
18f90 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
18fa0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
18fb0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
18fc0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
18fd0 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
18fe0 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
18ff0 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
19000 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
19010 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
19020 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
19030 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
19040 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
19050 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
19060 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
19070 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
19080 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
19090 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
190a0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
190b0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
190c0 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
190d0 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
190e0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
190f0 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
19100 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
19110 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
19120 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
19130 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
19140 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
19150 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
19160 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
19170 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
19180 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
19190 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
191a0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
191b0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
191c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
191d0 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
191e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
191f0 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
19200 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
19210 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
19220 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
19230 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
19240 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
19250 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
19260 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
19270 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
19280 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
19290 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
192a0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
192b0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
192c0 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
192d0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
192e0 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
192f0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
19300 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
19310 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
19320 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
19330 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
19340 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
19350 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
19360 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
19370 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
19380 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
19390 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
193a0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
193b0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
193c0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
193d0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
193e0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
193f0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
19400 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
19410 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
19420 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
19430 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
19440 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
19450 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
19460 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
19470 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  *sql);.SQLITE_AP
19480 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
19490 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
194a0 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
194b0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
194c0 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
194d0 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
194e0 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20  _BUSY Errors.** 
194f0 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d  KEYWORDS: {busy-
19500 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
19510 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d  } {busy handler}
19520 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
19530 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
19540 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20  (D,X,P) routine 
19550 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
19560 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68  function X.** th
19570 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
19580 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ked with argumen
19590 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  t P whenever.** 
195a0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
195b0 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64  de to access a d
195c0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73  atabase table as
195d0 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
195e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
195f0 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e  ction] D when an
19600 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
19610 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74  or process has t
19620 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e  he table locked.
19630 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
19640 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69  busy_handler() i
19650 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
19660 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a   to implement.**
19670 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
19680 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50  imeout()] and [P
19690 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
196a0 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ut]..**.** ^If t
196b0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
196c0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
196d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
196e0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
196f0 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
19700 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
19710 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
19720 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
19730 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
19740 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
19750 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
19760 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
19770 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
19780 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
19790 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
197a0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
197b0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
197c0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
197d0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
197e0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
197f0 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
19800 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
19810 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
19820 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
19830 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
19840 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
19850 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
19860 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
19870 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74  previously for t
19880 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20  he same locking 
19890 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
198a0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
198b0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
198c0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
198d0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
198e0 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
198f0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
19900 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20  SQLITE_BUSY] is 
19910 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74  returned.** to t
19920 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a  he application..
19930 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
19940 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
19950 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
19960 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
19970 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
19980 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
19990 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
199a0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
199b0 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
199c0 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
199d0 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
199e0 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
199f0 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
19a00 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
19a10 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
19a20 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
19a30 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
19a40 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
19a50 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
19a60 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
19a70 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
19a80 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
19a90 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  SY].** to the ap
19aa0 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61  plication instea
19ab0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
19ac0 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  e .** busy handl
19ad0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
19ae0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
19af0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
19b00 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
19b10 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
19b20 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
19b30 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
19b40 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
19b50 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
19b60 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
19b70 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
19b80 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
19b90 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
19ba0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
19bb0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
19bc0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
19bd0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
19be0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
19bf0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
19c00 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
19c10 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
19c20 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
19c30 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
19c40 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
19c50 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
19c60 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
19c70 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
19c80 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
19c90 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
19ca0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
19cb0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
19cc0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
19cd0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
19ce0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
19cf0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
19d00 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
19d10 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
19d20 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
19d30 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
19d40 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
19d50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
19d60 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
19d70 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
19d80 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
19d90 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
19da0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
19db0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
19dc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19dd0 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
19de0 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
19df0 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
19e00 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
19e10 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
19e20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
19e30 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
19e40 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c  ut()].** or eval
19e50 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62  uating [PRAGMA b
19e60 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77  usy_timeout=N] w
19e70 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a  ill change the.*
19e80 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61  * busy handler a
19e90 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e  nd thus clear an
19ea0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  y previously set
19eb0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
19ec0 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
19ed0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
19ee0 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
19ef0 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
19f00 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
19f10 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
19f20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
19f30 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74   handler.  In ot
19f40 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68  her words,.** th
19f50 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
19f60 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  s not reentrant.
19f70 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
19f80 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
19f90 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
19fa0 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
19fb0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
19fc0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
19fd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19fe0 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
19ff0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1a000 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1a010 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51  y handler..*/.SQ
1a020 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1a030 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a040 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
1a050 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
1a060 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1a070 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
1a080 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a  sy Timeout.**.**
1a090 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
1a0a0 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
1a0b0 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
1a0c0 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
1a0d0 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
1a0e0 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
1a0f0 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
1a100 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
1a110 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
1a120 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
1a130 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
1a140 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
1a150 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1a160 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
1a170 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
1a180 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
1a190 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1a1a0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
1a1b0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
1a1c0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
1a1d0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
1a1e0 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
1a1f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1a200 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1a210 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1a220 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
1a230 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
1a240 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
1a250 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
1a260 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
1a270 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1a280 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1a290 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
1a2a0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1a2b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a2c0 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e  on] at any given
1a2d0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
1a2e0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1a2f0 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
1a300 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
1a310 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1a320 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
1a330 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
1a340 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
1a350 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1a360 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  cleared.)^.**.**
1a370 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41   See also:  [PRA
1a380 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1a390 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
1a3a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1a3b0 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1a3c0 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1a3d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1a3e0 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1a3f0 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1a400 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eries.**.** This
1a410 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
1a420 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
1a430 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
1a440 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1a450 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
1a460 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
1a470 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
1a480 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
1a490 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
1a4a0 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
1a4b0 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
1a4c0 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
1a4d0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
1a4e0 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
1a4f0 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
1a500 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
1a510 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
1a520 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
1a530 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
1a540 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
1a550 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
1a560 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
1a570 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
1a580 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
1a590 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
1a5a0 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
1a5b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
1a5c0 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
1a5d0 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
1a5e0 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
1a5f0 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
1a600 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
1a610 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
1a620 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
1a630 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1a640 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
1a650 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
1a660 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1a670 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
1a680 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
1a690 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
1a6a0 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
1a6b0 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
1a6c0 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
1a6d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1a6e0 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
1a6f0 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
1a700 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
1a710 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
1a720 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
1a730 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
1a740 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
1a750 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
1a760 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
1a770 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
1a780 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
1a790 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1a7a0 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
1a7b0 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
1a7c0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1a7d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
1a7e0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1a7f0 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
1a800 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
1a810 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
1a820 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
1a830 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
1a840 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1a850 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
1a860 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
1a870 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1a880 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
1a890 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
1a8a0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1a8b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
1a8c0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
1a8d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
1a8e0 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
1a8f0 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
1a900 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1a910 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1a920 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1a930 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
1a940 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
1a950 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a960 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
1a970 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
1a980 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
1a990 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
1a9a0 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
1a9b0 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
1a9c0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1a9d0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
1a9e0 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
1a9f0 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
1aa00 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
1aa10 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
1aa20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
1aa30 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
1aa40 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
1aa50 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
1aa60 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
1aa70 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
1aa80 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
1aa90 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
1aaa0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1aab0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1aac0 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
1aad0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1aae0 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
1aaf0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1ab00 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
1ab10 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
1ab20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1ab30 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
1ab40 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1ab50 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
1ab60 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1ab70 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
1ab80 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1ab90 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
1aba0 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
1abb0 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
1abc0 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
1abd0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1abe0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1abf0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
1ac00 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
1ac10 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
1ac20 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
1ac30 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
1ac40 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
1ac50 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1ac60 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
1ac70 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
1ac80 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
1ac90 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
1aca0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
1acb0 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
1acc0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
1acd0 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
1ace0 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
1acf0 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
1ad00 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
1ad10 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
1ad20 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
1ad30 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
1ad40 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
1ad50 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
1ad60 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
1ad70 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
1ad80 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
1ad90 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
1ada0 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
1adb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1adc0 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
1add0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1ade0 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
1adf0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
1ae00 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
1ae10 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1ae20 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
1ae30 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
1ae40 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
1ae50 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
1ae60 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
1ae70 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
1ae80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1ae90 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
1aea0 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
1aeb0 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
1aec0 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
1aed0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
1aee0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1aef0 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
1af00 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
1af10 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
1af20 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
1af30 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
1af40 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
1af50 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
1af60 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
1af70 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
1af80 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
1af90 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
1afa0 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
1afb0 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
1afc0 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
1afd0 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
1afe0 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
1aff0 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
1b000 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
1b010 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1b020 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1b030 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53  _errmsg()]..*/.S
1b040 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1b050 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1b060 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1b070 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
1b080 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
1b090 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1b0a0 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
1b0b0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
1b0c0 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
1b0d0 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1b0e0 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1b0f0 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1b100 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1b110 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1b120 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1b130 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1b140 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1b150 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1b160 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1b170 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1b180 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1b190 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1b1a0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1b1b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1b1c0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
1b1d0 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
1b1e0 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
1b1f0 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
1b200 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
1b210 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1b220 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1b230 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
1b240 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
1b250 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
1b260 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
1b270 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1b280 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ary..**.** ^The 
1b290 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1b2a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
1b2b0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1b2c0 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
1b2d0 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
1b2e0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
1b2f0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
1b300 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
1b310 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1b320 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
1b330 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
1b340 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
1b350 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
1b360 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
1b370 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
1b380 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
1b390 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
1b3a0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
1b3b0 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
1b3c0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1b3d0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
1b3e0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ng..**.** ^(The 
1b3f0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1b400 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
1b410 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
1b420 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
1b430 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1b440 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
1b450 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
1b460 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
1b470 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
1b480 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1b490 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
1b4a0 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
1b4b0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
1b4c0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
1b4d0 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
1b4e0 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
1b4f0 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
1b500 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
1b510 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
1b520 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
1b530 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
1b540 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
1b550 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
1b560 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1b570 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
1b580 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
1b590 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
1b5a0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1b5b0 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
1b5c0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
1b5d0 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
1b5e0 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
1b5f0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
1b600 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
1b610 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
1b620 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
1b630 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
1b640 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
1b650 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
1b660 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
1b670 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
1b680 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
1b690 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1b6a0 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
1b6b0 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
1b6c0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
1b6d0 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
1b6e0 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
1b6f0 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
1b700 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1b710 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
1b720 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
1b730 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
1b740 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
1b750 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1b760 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
1b770 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
1b780 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
1b790 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
1b7a0 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
1b7b0 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
1b7c0 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
1b7d0 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
1b7e0 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
1b7f0 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
1b800 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  acters..**.** ^T
1b810 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  he sqlite3_vsnpr
1b820 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1b830 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73  s a varargs vers
1b840 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1b850 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a  nprintf()..**.**
1b860 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1b870 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
1b880 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
1b890 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
1b8a0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
1b8b0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
1b8c0 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
1b8d0 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
1b8e0 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
1b8f0 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
1b900 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
1b910 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
1b920 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
1b930 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
1b940 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
1b950 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
1b960 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
1b970 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
1b980 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  es a nul-termina
1b990 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
1b9a0 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
1b9b0 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
1b9c0 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
1b9d0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
1b9e0 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
1b9f0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
1ba00 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
1ba10 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69  al.)^  By doubli
1ba20 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
1ba30 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
1ba40 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
1ba50 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
1ba60 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
1ba70 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
1ba80 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
1ba90 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
1baa0 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
1bab0 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
1bac0 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
1bad0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1bae0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1baf0 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
1bb00 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
1bb10 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1bb20 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
1bb30 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
1bb40 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
1bb50 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
1bb60 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1bb70 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1bb80 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1bb90 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1bba0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1bbb0 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
1bbc0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1bbd0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1bbe0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1bbf0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1bc00 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1bc10 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1bc20 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
1bc30 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
1bc40 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
1bc50 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
1bc60 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
1bc70 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
1bc80 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
1bc90 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1bca0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1bcb0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1bcc0 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1bcd0 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
1bce0 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
1bcf0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1bd00 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
1bd10 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
1bd20 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
1bd30 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
1bd40 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
1bd50 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
1bd60 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1bd70 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1bd80 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1bd90 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
1bda0 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
1bdb0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1bdc0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1bdd0 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
1bde0 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
1bdf0 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
1be00 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
1be10 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
1be20 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
1be30 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
1be40 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
1be50 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
1be60 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70  *.** ^(The %Q op
1be70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1be80 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
1be90 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
1bea0 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
1beb0 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
1bec0 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
1bed0 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
1bee0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1bef0 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
1bf00 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
1bf10 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
1bf20 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
1bf30 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
1bf40 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
1bf50 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72  tes).)^  So, for
1bf60 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
1bf70 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
1bf80 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1bf90 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1bfa0 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1bfb0 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1bfc0 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
1bfd0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1bfe0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1bff0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1c000 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1c010 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1c020 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1c030 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
1c040 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
1c050 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
1c060 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
1c070 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
1c080 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
1c090 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
1c0a0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1c0b0 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f  ** ^(The "%z" fo
1c0c0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1c0d0 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20  works like "%s" 
1c0e0 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  but with the.** 
1c0f0 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
1c100 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
1c110 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
1c120 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
1c130 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
1c140 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
1c150 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
1c160 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f  put string.)^.*/
1c170 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1c180 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
1c190 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
1c1a0 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .);.SQLITE_API c
1c1b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
1c1c0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1c1d0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c  *, va_list);.SQL
1c1e0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
1c1f0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
1c200 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1c210 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49  har*, ...);.SQLI
1c220 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
1c230 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1c240 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1c250 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1c260 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c270 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1c280 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1c290 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1c2a0 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1c2b0 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1c2c0 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1c2d0 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1c2e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1c2f0 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1c300 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1c310 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1c320 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1c330 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1c340 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1c350 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1c360 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1c370 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1c380 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1c390 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1c3a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c3b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1c3c0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1c3d0 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1c3e0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1c3f0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1c400 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1c410 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1c420 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1c430 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1c440 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1c450 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1c460 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1c470 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1c480 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1c490 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1c4a0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c4b0 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1c4c0 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1c4d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1c4e0 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1c4f0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
1c500 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1c510 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f  64(N) routine wo
1c520 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a  rks just like.**
1c530 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c540 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1c550 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
1c560 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69  64-bit integer i
1c570 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73  nstead.** of a s
1c580 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74  igned 32-bit int
1c590 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  eger..**.** ^Cal
1c5a0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1c5b0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1c5c0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1c5d0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1c5e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1c5f0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c600 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1c610 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1c620 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1c630 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1c640 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1c650 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1c660 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1c670 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1c680 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1c690 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1c6a0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1c6b0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1c6c0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1c6d0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1c6e0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1c6f0 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1c700 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1c710 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1c720 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1c730 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1c740 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1c750 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1c760 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1c770 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1c780 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1c790 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1c7a0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1c7b0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1c7c0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1c7d0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1c7e0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1c7f0 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1c800 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1c810 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1c820 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1c830 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c840 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1c850 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1c860 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1c870 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1c880 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62  llocation X to b
1c890 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1c8a0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58  es..** ^If the X
1c8b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1c8c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1c8d0 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  N).** is a NULL 
1c8e0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1c8f0 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1c900 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1c910 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1c920 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74  loc(N)..** ^If t
1c930 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
1c940 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1c950 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f  c(X,N) is zero o
1c960 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1c970 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1c980 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1c990 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1c9a0 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58  * sqlite3_free(X
1c9b0 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1c9c0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1c9d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1c9e0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1c9f0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1ca00 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1ca10 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ize or NULL if i
1ca20 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
1ca30 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  ry is available.
1ca40 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1ca50 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1ca60 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1ca70 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1ca80 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1ca90 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1caa0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1cab0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1cac0 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1cad0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1cae0 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68  lloc(X,N) and th
1caf0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1cb00 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1cb10 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1cb20 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1cb30 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70   NULL and N is p
1cb40 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68  ositive, then th
1cb50 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63  e.** prior alloc
1cb60 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65  ation is not fre
1cb70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1cb80 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1cb90 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73  (X,N) interfaces
1cba0 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
1cbb0 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  as.** sqlite3_re
1cbc0 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70  alloc(X,N) excep
1cbd0 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34  t that N is a 64
1cbe0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1cbf0 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1cc00 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
1cc10 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1cc20 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65  ** ^If X is a me
1cc30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1cc40 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
1cc50 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1cc60 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  _malloc(),.** sq
1cc70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1cc80 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1cc90 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  c(), or sqlite3_
1cca0 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65  realloc64(), the
1ccb0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1ccc0 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  ze(X) returns th
1ccd0 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d  e size of that m
1cce0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1ccf0 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54   in bytes..** ^T
1cd00 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1cd10 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69  d by sqlite3_msi
1cd20 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c  ze(X) might be l
1cd30 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e  arger than the n
1cd40 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
1cd50 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e  s requested when
1cd60 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64   X was allocated
1cd70 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55  .  ^If X is a NU
1cd80 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
1cd90 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1cda0 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (X) returns zero
1cdb0 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74  .  If X points t
1cdc0 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74  o something that
1cdd0 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62   is not.** the b
1cde0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f  eginning of memo
1cdf0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f  ry allocation, o
1ce00 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74  r if it points t
1ce10 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20  o a formerly.** 
1ce20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  valid memory all
1ce30 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73  ocation that has
1ce40 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c   now been freed,
1ce50 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1ce60 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  or.** of sqlite3
1ce70 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64  _msize(X) is und
1ce80 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69  efined and possi
1ce90 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
1cea0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1ceb0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1cec0 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c  e3_malloc(), sql
1ced0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a  ite3_realloc(),.
1cee0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1cef0 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  c64(), and sqlit
1cf00 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a  e3_realloc64().*
1cf10 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
1cf20 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
1cf30 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
1cf40 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
1cf50 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
1cf60 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
1cf70 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
1cf80 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
1cf90 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
1cfa0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
1cfb0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1cfc0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
1cfd0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
1cfe0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
1cff0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
1d000 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
1d010 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
1d020 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
1d030 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1d040 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1d050 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
1d060 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
1d070 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
1d080 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
1d090 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1d0a0 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
1d0b0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
1d0c0 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
1d0d0 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
1d0e0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
1d0f0 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
1d100 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
1d110 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
1d120 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
1d130 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
1d140 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
1d150 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
1d160 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
1d170 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
1d180 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
1d190 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
1d1a0 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
1d1b0 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
1d1c0 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
1d1d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
1d1e0 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
1d1f0 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1d200 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
1d210 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
1d220 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
1d230 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
1d240 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1d250 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
1d260 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
1d270 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
1d280 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
1d290 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1d2a0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
1d2b0 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
1d2c0 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
1d2d0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
1d2e0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
1d2f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1d300 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1d310 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
1d320 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
1d330 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
1d340 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1d350 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
1d360 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
1d370 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
1d380 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
1d390 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
1d3a0 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
1d3b0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1d3c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1d3d0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  lloc()]..*/.SQLI
1d3e0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
1d3f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
1d400 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1d410 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1d420 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74  c64(sqlite3_uint
1d430 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
1d440 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1d450 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
1d460 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1d470 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1d480 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c  loc64(void*, sql
1d490 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51  ite3_uint64);.SQ
1d4a0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
1d4b0 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
1d4c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
1d4d0 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c  lite3_uint64 sql
1d4e0 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a  ite3_msize(void*
1d4f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d500 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1d510 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
1d520 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
1d530 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
1d540 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
1d550 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
1d560 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
1d570 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1d580 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
1d590 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
1d5a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1d5b0 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
1d5c0 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
1d5d0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1d5e0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
1d5f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
1d600 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1d610 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1d620 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1d630 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
1d640 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
1d650 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
1d660 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
1d670 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
1d680 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1d690 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
1d6a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
1d6b0 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
1d6c0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
1d6d0 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
1d6e0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1d6f0 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
1d700 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
1d710 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
1d720 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1d730 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1d740 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1d750 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
1d760 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
1d770 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
1d780 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
1d790 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
1d7a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1d7b0 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
1d7c0 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
1d7d0 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
1d7e0 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
1d7f0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
1d800 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1d810 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
1d820 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1d830 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
1d840 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
1d850 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
1d860 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1d870 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
1d880 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
1d890 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
1d8a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1d8b0 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
1d8c0 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
1d8d0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1d8e0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1d8f0 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
1d900 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1d910 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
1d920 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53   the reset..*/.S
1d930 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
1d940 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1d950 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
1d960 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
1d970 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1d980 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1d990 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
1d9a0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
1d9b0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
1d9c0 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
1d9d0 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
1d9e0 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
1d9f0 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
1da00 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
1da10 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
1da20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
1da30 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
1da40 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
1da50 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
1da60 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
1da70 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
1da80 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
1da90 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
1daa0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
1dab0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
1dac0 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
1dad0 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
1dae0 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
1daf0 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
1db00 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
1db10 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
1db20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
1db30 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
1db40 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
1db50 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
1db60 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
1db70 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
1db80 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
1db90 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  er P..** ^The P 
1dba0 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65  parameter can be
1dbb0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1dbc0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20  .**.** ^If this 
1dbd0 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20  routine has not 
1dbe0 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  been previously 
1dbf0 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65  called or if the
1dc00 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c   previous.** cal
1dc10 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61  l had N less tha
1dc20 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20  n one or a NULL 
1dc30 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74  pointer for P, t
1dc40 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a  hen the PRNG is.
1dc50 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  ** seeded using 
1dc60 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
1dc70 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61  ned from the xRa
1dc80 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1dc90 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  of.** the defaul
1dca0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1dcb0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74  object..** ^If t
1dcc0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
1dcd0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1dce0 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f   had an N of 1 o
1dcf0 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20  r more and a.** 
1dd00 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20  non-NULL P then 
1dd10 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
1dd20 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
1dd30 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
1dd40 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
1dd50 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
1dd60 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
1dd70 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
1dd80 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1dd90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
1dda0 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
1ddb0 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
1ddc0 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
1ddd0 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
1dde0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
1ddf0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1de00 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
1de10 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1de20 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
1de30 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1de40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
1de50 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
1de60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
1de70 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
1de80 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1de90 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
1dea0 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
1deb0 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
1dec0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
1ded0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1dee0 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
1def0 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
1df00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1df10 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
1df20 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1df30 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
1df40 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
1df50 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
1df60 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
1df70 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
1df80 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
1df90 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
1dfa0 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
1dfb0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1dfc0 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
1dfd0 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
1dfe0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
1dff0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1e000 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1e010 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1e020 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
1e030 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
1e040 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
1e050 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
1e060 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
1e070 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
1e080 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
1e090 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
1e0a0 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
1e0b0 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
1e0c0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
1e0d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1e0e0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
1e0f0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
1e100 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
1e110 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
1e120 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
1e130 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
1e140 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
1e150 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
1e160 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
1e170 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
1e180 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1e190 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1e1a0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
1e1b0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1e1c0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1e1d0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1e1e0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
1e1f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1e200 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
1e210 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
1e220 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
1e230 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
1e240 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1e250 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1e260 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
1e270 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e280 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1e290 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1e2a0 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
1e2b0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1e2c0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1e2d0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
1e2e0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
1e2f0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
1e300 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1e310 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1e320 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e330 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
1e340 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
1e350 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1e360 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1e370 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
1e380 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
1e390 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
1e3a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1e3b0 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
1e3c0 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
1e3d0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
1e3e0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
1e3f0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
1e400 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1e410 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
1e420 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
1e430 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
1e440 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
1e450 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1e460 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
1e470 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
1e480 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
1e490 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1e4a0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
1e4b0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1e4c0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
1e4d0 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
1e4e0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1e4f0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1e500 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
1e510 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e520 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
1e530 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
1e540 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
1e550 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
1e560 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1e570 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
1e580 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
1e590 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
1e5a0 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
1e5b0 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
1e5c0 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
1e5d0 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
1e5e0 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
1e5f0 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
1e600 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
1e610 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
1e620 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
1e630 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1e640 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
1e650 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1e660 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
1e670 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1e680 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
1e690 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
1e6a0 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
1e6b0 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
1e6c0 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
1e6d0 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
1e6e0 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
1e6f0 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
1e700 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
1e710 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
1e720 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1e730 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
1e740 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
1e750 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1e760 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
1e770 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1e780 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
1e790 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
1e7a0 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
1e7b0 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
1e7c0 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
1e7d0 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
1e7e0 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
1e7f0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
1e800 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
1e810 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
1e820 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
1e830 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
1e840 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
1e850 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
1e860 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
1e870 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
1e880 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
1e890 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
1e8a0 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
1e8b0 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
1e8c0 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
1e8d0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
1e8e0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
1e8f0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
1e900 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
1e910 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
1e920 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
1e930 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
1e940 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1e950 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
1e960 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
1e970 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
1e980 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1e990 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
1e9a0 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
1e9b0 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
1e9c0 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
1e9d0 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
1e9e0 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
1e9f0 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
1ea00 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
1ea10 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
1ea20 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
1ea30 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
1ea40 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
1ea50 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
1ea60 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
1ea70 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
1ea80 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
1ea90 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
1eaa0 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
1eab0 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
1eac0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ead0 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
1eae0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
1eaf0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1eb00 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
1eb10 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
1eb20 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
1eb30 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
1eb40 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
1eb50 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
1eb60 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1eb70 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
1eb80 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
1eb90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1eba0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1ebb0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1ebc0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1ebd0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1ebe0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1ebf0 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
1ec00 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
1ec10 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1ec20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1ec30 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1ec40 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1ec50 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1ec60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1ec70 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1ec80 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1ec90 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1eca0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
1ecb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1ecc0 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
1ecd0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1ece0 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
1ecf0 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
1ed00 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
1ed10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1ed20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
1ed30 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
1ed40 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
1ed50 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
1ed60 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
1ed70 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
1ed80 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
1ed90 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
1eda0 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
1edb0 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
1edc0 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
1edd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ede0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
1edf0 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
1ee00 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1ee10 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
1ee20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
1ee30 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
1ee40 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
1ee50 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
1ee60 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
1ee70 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
1ee80 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
1ee90 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
1eea0 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
1eeb0 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
1eec0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1eed0 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
1eee0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
1eef0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
1ef00 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1ef10 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
1ef20 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
1ef30 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
1ef40 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
1ef50 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1ef60 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1ef70 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1ef80 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
1ef90 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
1efa0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1efb0 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
1efc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1efd0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1efe0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1eff0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1f000 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
1f010 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
1f020 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
1f030 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
1f040 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
1f050 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
1f060 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1f070 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
1f080 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
1f090 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
1f0a0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1f0b0 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
1f0c0 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
1f0d0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1f0e0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
1f0f0 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
1f100 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
1f110 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74  d as a [conflict
1f120 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65   resolution mode
1f130 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72  ].** returned fr
1f140 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
1f150 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
1f160 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
1f170 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f180 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
1f190 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
1f1a0 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
1f1b0 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
1f1c0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
1f1d0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
1f1e0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
1f1f0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
1f200 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
1f210 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1f220 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
1f230 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1f240 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1f250 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
1f260 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
1f270 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
1f280 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
1f290 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
1f2a0 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
1f2b0 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
1f2c0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1f2d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
1f2e0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1f2f0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
1f300 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
1f310 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
1f320 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1f330 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
1f340 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
1f350 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
1f360 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1f370 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
1f380 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
1f390 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
1f3a0 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
1f3b0 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
1f3c0 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
1f3d0 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
1f3e0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
1f3f0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1f400 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
1f410 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
1f420 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
1f430 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
1f440 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
1f450 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
1f460 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1f470 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
1f480 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
1f490 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
1f4a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1f4b0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1f4c0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
1f4d0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
1f4e0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1f4f0 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
1f500 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1f510 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f520 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
1f530 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
1f540 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
1f550 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
1f560 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
1f570 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
1f580 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
1f590 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
1f5a0 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
1f5b0 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
1f5c0 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
1f5d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f5e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f5f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
1f600 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
1f610 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
1f620 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1f630 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
1f640 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
1f650 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1f660 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1f670 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1f680 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
1f690 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
1f6a0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1f6b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f6c0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1f6d0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1f6e0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
1f6f0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1f700 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1f710 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1f720 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
1f730 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1f740 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f750 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f760 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1f770 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
1f780 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1f790 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1f7a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f7b0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1f7c0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
1f7d0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1f7e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f7f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f800 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
1f810 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
1f820 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1f830 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1f840 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f850 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
1f860 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
1f870 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1f880 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f890 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f8a0 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
1f8b0 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
1f8c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f8d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f8e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f8f0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
1f900 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
1f910 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1f920 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f930 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f940 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
1f950 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
1f960 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f970 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f980 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f990 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
1f9a0 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
1f9b0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1f9c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f9d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f9e0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
1f9f0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
1fa00 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1fa10 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1fa20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1fa30 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
1fa40 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
1fa50 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1fa60 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1fa70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1fa80 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
1fa90 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
1faa0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1fab0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1fac0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1fad0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
1fae0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
1faf0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1fb00 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1fb10 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1fb20 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1fb30 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
1fb40 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1fb50 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1fb60 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
1fb70 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1fb80 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
1fb90 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1fba0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1fbb0 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
1fbc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1fbd0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
1fbe0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
1fbf0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
1fc00 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
1fc10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
1fc20 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1fc30 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1fc40 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1fc50 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
1fc60 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
1fc70 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1fc80 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1fc90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fca0 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
1fcb0 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
1fcc0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1fcd0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1fce0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fcf0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
1fd00 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
1fd10 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1fd20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1fd30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fd40 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
1fd50 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
1fd60 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
1fd70 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1fd80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1fd90 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
1fda0 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
1fdb0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1fdc0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1fdd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fde0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
1fdf0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
1fe00 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1fe10 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1fe20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fe30 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
1fe40 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
1fe50 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
1fe60 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1fe70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fe80 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
1fe90 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
1fea0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1feb0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1fec0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fed0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
1fee0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
1fef0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1ff00 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1ff10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ff20 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
1ff30 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
1ff40 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1ff50 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1ff60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
1ff70 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
1ff80 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
1ff90 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
1ffa0 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
1ffb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
1ffc0 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
1ffd0 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
1ffe0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
1fff0 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
20000 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
20010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20020 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
20030 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
20040 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53  ne SQLITE_RECURS
20050 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33  IVE            3
20060 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  3   /* NULL     
20070 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
20080 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a         */../*.**
20090 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
200a0 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
200b0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
200c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
200d0 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
200e0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
200f0 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
20100 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
20110 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
20120 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
20130 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
20140 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
20150 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
20160 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
20170 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
20180 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
20190 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
201a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
201b0 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
201c0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
201d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
201e0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
201f0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
20200 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
20210 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
20220 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
20230 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
20240 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
20250 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
20260 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
20270 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
20280 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
20290 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
202a0 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
202b0 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
202c0 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
202d0 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
202e0 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
202f0 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
20300 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
20310 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ^.**.** The [SQL
20320 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
20330 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
20340 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  me option can be
20350 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a   used to limit.*
20360 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * the length of 
20370 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
20380 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74  ] expansion in t
20390 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c  he output of sql
203a0 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a  ite3_trace()..**
203b0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
203c0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
203d0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
203e0 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
203f0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
20400 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
20410 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
20420 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
20430 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
20440 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
20450 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
20460 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
20470 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
20480 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
20490 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
204a0 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
204b0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
204c0 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
204d0 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
204e0 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
204f0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
20500 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
20510 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
20520 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
20530 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
20540 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
20550 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
20560 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
20570 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
20580 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
20590 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
205a0 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
205b0 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
205c0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
205d0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
205e0 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
205f0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
20600 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
20610 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
20620 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
20630 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
20640 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
20650 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
20660 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
20670 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28  , void(*xTrace)(
20680 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
20690 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
206a0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58  TE_API SQLITE_EX
206b0 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
206c0 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
206d0 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
206e0 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
206f0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
20700 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
20710 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
20720 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
20730 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
20740 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
20750 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
20760 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
20770 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
20780 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
20790 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
207a0 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
207b0 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
207c0 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
207d0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
207e0 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
207f0 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
20800 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
20810 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
20820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
20830 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
20840 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
20850 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
20860 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
20870 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
20880 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
20890 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
208a0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
208b0 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
208c0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
208d0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
208e0 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
208f0 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61  meter N is the a
20900 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65  pproximate numbe
20910 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
20920 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
20930 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
20940 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
20950 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
20960 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
20970 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20  the callback X. 
20980 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74   ^If N is less t
20990 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65  han one then the
209a0 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e   progress.** han
209b0 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  dler is disabled
209c0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
209d0 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
209e0 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
209f0 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
20a00 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
20a10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
20a20 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
20a30 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
20a40 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
20a50 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
20a60 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
20a70 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables t
20a80 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
20a90 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
20aa0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
20ab0 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
20ac0 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
20ad0 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
20ae0 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
20af0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
20b00 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
20b10 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
20b20 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
20b30 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
20b40 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
20b50 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
20b60 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
20b70 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
20b80 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
20b90 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
20ba0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
20bb0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
20bc0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
20bd0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
20be0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
20bf0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
20c00 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
20c10 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
20c20 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
20c30 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
20c40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
20c50 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
20c60 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
20c70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
20c80 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
20c90 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
20ca0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
20cb0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
20cc0 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
20cd0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
20ce0 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
20cf0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
20d00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20d10 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
20d20 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
20d30 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
20d40 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
20d50 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
20d60 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
20d70 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
20d80 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
20d90 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
20da0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
20db0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
20dc0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
20dd0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
20de0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
20df0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
20e00 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
20e10 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
20e20 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
20e30 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
20e40 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
20e50 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
20e60 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
20e70 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
20e80 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
20e90 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
20ea0 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
20eb0 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
20ec0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
20ed0 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
20ee0 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
20ef0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
20f00 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
20f10 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
20f20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
20f30 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
20f40 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
20f50 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
20f60 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
20f70 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
20f80 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
20f90 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
20fa0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
20fb0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
20fc0 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
20fd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
20fe0 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
20ff0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
21000 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
21010 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
21020 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
21030 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
21040 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
21050 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
21060 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
21070 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
21080 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
21090 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
210a0 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20  ncoding will be 
210b0 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61  UTF-8 for databa
210c0 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e  ses created usin
210d0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  g.** sqlite3_ope
210e0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
210f0 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20  pen_v2().  ^The 
21100 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
21110 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a   for databases.*
21120 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  * created using 
21130 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
21140 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20   will be UTF-16 
21150 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
21160 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20  te order..**.** 
21170 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
21180 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
21190 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
211a0 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
211b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
211c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
211d0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
211e0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
211f0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
21200 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
21210 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
21220 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
21230 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
21240 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
21250 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
21260 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
21270 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
21280 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
21290 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
212a0 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
212b0 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
212c0 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
212d0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
212e0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
212f0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
21300 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
21310 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
21320 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
21330 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
21340 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
21350 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
21360 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
21370 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
21380 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
21390 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
213a0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
213b0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
213c0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c  N_PRIVATECACHE],
213d0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
213e0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a  OPEN_URI] flags:
213f0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
21400 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
21410 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
21420 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
21430 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
21440 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
21450 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
21460 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
21470 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
21480 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
21490 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
214a0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
214b0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
214c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
214d0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
214e0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
214f0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
21500 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
21510 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
21520 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
21530 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
21540 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
21550 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
21560 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
21570 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
21580 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
21590 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
215a0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
215b0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
215c0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
215d0 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
215e0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
215f0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
21600 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
21610 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
21620 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
21630 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f  ated if.** it do
21640 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
21650 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
21660 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
21670 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
21680 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
21690 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
216a0 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
216b0 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
216c0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
216d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
216e0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
216f0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
21700 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
21710 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61  wn above optiona
21720 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
21730 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49  h other.** [SQLI
21740 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
21750 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a   | SQLITE_OPEN_*
21760 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74   bits].** then t
21770 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
21780 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
21790 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
217a0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
217b0 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
217c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
217d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
217e0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
217f0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
21800 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
21810 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
21820 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
21830 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
21840 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
21850 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
21860 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
21870 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
21880 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
21890 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
218a0 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
218b0 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
218c0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
218d0 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
218e0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
218f0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
21900 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
21910 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
21920 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
21930 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
21940 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
21950 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
21960 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
21970 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
21980 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
21990 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
219a0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
219b0 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
219c0 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
219d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
219e0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
219f0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
21a00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
21a10 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
21a20 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
21a30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
21a40 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
21a50 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
21a60 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
21a70 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
21a80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
21a90 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
21aa0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21ab0 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
21ac0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
21ad0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
21ae0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
21af0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
21b00 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
21b10 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
21b20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
21b30 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
21b40 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
21b50 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
21b60 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
21b70 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
21b80 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
21b90 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
21ba0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
21bb0 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
21bc0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
21bd0 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
21be0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
21bf0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
21c00 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
21c10 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
21c20 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
21c30 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
21c40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21c50 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
21c60 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
21c70 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
21c80 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
21c90 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
21ca0 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
21cb0 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
21cc0 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
21cd0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
21ce0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
21cf0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
21d00 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
21d10 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
21d20 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
21d30 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
21d40 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
21d50 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
21d60 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
21d70 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
21d80 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
21d90 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
21da0 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
21db0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
21dc0 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
21dd0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
21de0 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
21df0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
21e00 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
21e10 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
21e20 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
21e30 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
21e40 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
21e50 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
21e60 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65  enames in sqlite
21e70 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55  3_open()]] <h3>U
21e80 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33  RI Filenames</h3
21e90 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49  >.**.** ^If [URI
21ea0 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72   filename] inter
21eb0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
21ec0 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69  bled, and the fi
21ed0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
21ee0 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22  ** begins with "
21ef0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65  file:", then the
21f00 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74   filename is int
21f10 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52  erpreted as a UR
21f20 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e  I. ^URI.** filen
21f30 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
21f40 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  on is enabled if
21f50 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
21f60 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a  N_URI] flag is.*
21f70 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75  * set in the fou
21f80 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
21f90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21fa0 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
21fb0 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
21fc0 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
21fd0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
21fe0 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
21ff0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
22000 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
22010 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
22020 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
22030 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
22040 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c  on..** As of SQL
22050 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
22060 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  7, URI filename 
22070 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
22080 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
22090 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
220a0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
220b0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
220c0 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
220d0 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
220e0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
220f0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
22100 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
22110 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
22120 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
22130 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
22140 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
22150 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
22160 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
22170 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
22180 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
22190 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
221a0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
221b0 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
221c0 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
221d0 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
221e0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
221f0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
22200 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
22210 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
22220 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
22230 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
22240 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
22250 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
22260 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
22270 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
22280 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
22290 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
222a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
222b0 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
222c0 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
222d0 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
222e0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
222f0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
22300 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
22310 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
22320 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
22330 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
22340 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
22350 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
22360 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
22370 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
22380 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
22390 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
223a0 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
223b0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
223c0 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
223d0 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74   ^(On windows, t
223e0 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65  he first compone
223f0 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74  nt of an absolut
22400 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20  e path .** is a 
22410 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74  drive specificat
22420 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e  ion (e.g. "C:").
22430 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20  )^.**.** [[core 
22440 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65  URI query parame
22450 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75  ters]].** The qu
22460 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
22470 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61   a URI may conta
22480 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  in parameters th
22490 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  at are interpret
224a0 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20  ed.** either by 
224b0 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f  SQLite itself, o
224c0 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75  r by a [VFS | cu
224d0 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
224e0 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
224f0 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c  ite and its buil
22500 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74  t-in [VFSes] int
22510 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f  erpret the.** fo
22520 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61  llowing query pa
22530 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
22540 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
22550 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
22560 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
22570 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
22580 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
22590 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
225a0 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
225b0 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
225c0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
225d0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
225e0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
225f0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
22600 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
22610 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
22620 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
22630 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
22640 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
22650 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
22660 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
22670 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
22680 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
22690 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
226a0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
226b0 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
226c0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
226d0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
226e0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
226f0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
22700 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
22710 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
22720 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
22730 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
22740 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
22750 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
22760 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
22770 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
22780 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
22790 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
227a0 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
227b0 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
227c0 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
227d0 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
227e0 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
227f0 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
22800 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
22810 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
22820 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
22830 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
22840 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
22850 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
22860 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
22870 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
22880 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
22890 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
228a0 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
228b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
228c0 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
228d0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
228e0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
228f0 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
22900 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
22910 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
22920 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
22930 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
22940 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
22950 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
22960 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
22970 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
22980 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
22990 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
229a0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
229b0 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
229c0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
229d0 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
229e0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20  E_OPEN_CREATE.  
229f0 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
22a00 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65  ion is.**     se
22a10 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68  t to "memory" th
22a20 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65  en a pure [in-me
22a30 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74  mory database] t
22a40 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a  hat never reads.
22a50 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73  **     or writes
22a60 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73   from disk is us
22a70 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72  ed. ^It is an er
22a80 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
22a90 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20   value for.**   
22aa0 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d    the mode param
22ab0 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73  eter that is les
22ac0 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
22ad0 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
22ae0 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20  d by.**     the 
22af0 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20  flags passed in 
22b00 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
22b10 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
22b20 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
22b30 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
22b40 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
22b50 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
22b60 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
22b70 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
22b80 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
22b90 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
22ba0 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
22bb0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
22bc0 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
22bd0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
22be0 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
22bf0 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
22c00 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
22c10 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
22c20 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
22c30 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
22c40 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
22c50 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
22c60 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
22c70 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
22c80 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
22c90 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
22ca0 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
22cb0 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
22cc0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
22cd0 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
22ce0 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
22cf0 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
22d00 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72  des any behavior
22d10 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65   requested by se
22d20 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c  tting.**     SQL
22d30 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
22d40 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f  CACHE or SQLITE_
22d50 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
22d60 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c   flag..**.**  <l
22d70 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20  i> <b>psow</b>: 
22d80 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65  ^The psow parame
22d90 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68  ter indicates wh
22da0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
22db0 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61  .**     [powersa
22dc0 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72  fe overwrite] pr
22dd0 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64  operty does or d
22de0 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f  oes not apply to
22df0 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72   the.**     stor
22e00 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69  age media on whi
22e10 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ch the database 
22e20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a  file resides..**
22e30 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c  .**  <li> <b>nol
22e40 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f  ock</b>: ^The no
22e50 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  lock parameter i
22e60 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
22e70 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  y parameter.**  
22e80 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20     which if set 
22e90 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f  disables file lo
22ea0 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63  cking in rollbac
22eb0 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e  k journal modes.
22ec0 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73    This.**     is
22ed0 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65   useful for acce
22ee0 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65  ssing a database
22ef0 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d   on a filesystem
22f00 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a   that does not.*
22f10 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f  *     support lo
22f20 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a  cking.  Caution:
22f30 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75    Database corru
22f40 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75  ption might resu
22f50 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20  lt if two.**    
22f60 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73   or more process
22f70 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20  es write to the 
22f80 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e  same database an
22f90 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f  d any one of tho
22fa0 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73  se.**     proces
22fb0 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d  ses uses nolock=
22fc0 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  1..**.**  <li> <
22fd0 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a  b>immutable</b>:
22fe0 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20   ^The immutable 
22ff0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
23000 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20  oolean query.** 
23010 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68      parameter th
23020 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  at indicates tha
23030 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  t the database f
23040 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e  ile is stored on
23050 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c  .**     read-onl
23060 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20  y media.  ^When 
23070 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74  immutable is set
23080 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  , SQLite assumes
23090 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
230a0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63   database file c
230b0 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
230c0 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63  , even by a proc
230d0 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a  ess with higher.
230e0 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65  **     privilege
230f0 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74  , and so the dat
23100 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
23110 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c  read-only and al
23120 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20  l locking.**    
23130 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65   and change dete
23140 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65  ction is disable
23150 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74  d.  Caution: Set
23160 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62  ting the immutab
23170 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72  le.**     proper
23180 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ty on a database
23190 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20   file that does 
231a0 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63  in fact change c
231b0 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20  an result.**    
231c0 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75   in incorrect qu
231d0 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f  ery results and/
231e0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  or [SQLITE_CORRU
231f0 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20  PT] errors..**  
23200 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51     See also: [SQ
23210 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
23220 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20  ABLE]..**       
23230 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
23240 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
23250 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72  nknown parameter
23260 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f   in the query co
23270 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
23280 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72   is not an.** er
23290 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72  ror.  Future ver
232a0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
232b0 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64  might understand
232c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72   additional quer
232d0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  y.** parameters.
232e0 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61    See "[query pa
232f0 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70  rameters with sp
23300 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f  ecial meaning to
23310 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a   SQLite]" for.**
23320 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
23330 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  rmation..**.** [
23340 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  [URI filename ex
23350 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49  amples]] <h3>URI
23360 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
23370 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74  es</h3>.**.** <t
23380 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20  able border="1" 
23390 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c  align=center cel
233a0 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c  lpadding=5>.** <
233b0 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65  tr><th> URI file
233c0 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c  names <th> Resul
233d0 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  ts.** <tr><td> f
233e0 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e  ile:data.db <td>
233f0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
23400 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
23410 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
23420 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a  rent directory..
23430 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
23440 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
23450 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20  .db<br>.**      
23460 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65      file:///home
23470 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
23480 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r> .**          
23490 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74  file://localhost
234a0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
234b0 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a  db <br> <td> .**
234c0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
234d0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
234e0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
234f0 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  a.db"..** <tr><t
23500 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74  d> file://darkst
23510 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ar/home/fred/dat
23520 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
23530 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
23540 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e   "darkstar" is n
23550 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20  ot a recognized 
23560 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74  authority..** <t
23570 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69  r><td style="whi
23580 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22  te-space:nowrap"
23590 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
235a0 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65  ile:///C:/Docume
235b0 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74  nts%20and%20Sett
235c0 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f  ings/fred/Deskto
235d0 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20  p/data.db.**    
235e0 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e   <td> Windows on
235f0 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c  ly: Open the fil
23600 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66  e "data.db" on f
23610 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e  red's desktop on
23620 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20   drive.**       
23630 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74     C:. Note that
23640 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e   the %20 escapin
23650 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c  g in this exampl
23660 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c  e is not strictl
23670 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  y .**          n
23680 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65  ecessary - space
23690 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20   characters can 
236a0 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c  be used literall
236b0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  y.**          in
236c0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a   URI filenames..
236d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
236e0 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f  :data.db?mode=ro
236f0 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c  &cache=private <
23700 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
23710 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61   Open file "data
23720 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
23730 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f  ent directory fo
23740 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65  r read-only acce
23750 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss..**          
23760 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
23770 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
23780 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69  red-cache mode i
23790 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20  s enabled by.** 
237a0 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74           default
237b0 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20  , use a private 
237c0 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cache..** <tr><t
237d0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
237e0 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75  ed/data.db?vfs=u
237f0 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e  nix-dotfile <td>
23800 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
23810 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  n file "/home/fr
23820 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65  ed/data.db". Use
23830 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
23840 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a   "unix-dotfile".
23850 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
23860 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20   uses dot-files 
23870 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69  in place of posi
23880 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69  x advisory locki
23890 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ng..** <tr><td> 
238a0 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
238b0 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20  e=readonly <td> 
238c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
238d0 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79  error. "readonly
238e0 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64  " is not a valid
238f0 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20   option for the 
23900 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72  "mode" parameter
23910 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ..** </table>.**
23920 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63  .** ^URI hexadec
23930 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
23940 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20  ences (%HH) are 
23950 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
23960 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a   the path and.**
23970 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
23980 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65  s of a URI. A he
23990 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
239a0 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73   sequence consis
239b0 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65  ts of a.** perce
239c0 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20  nt sign - "%" - 
239d0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63  followed by exac
239e0 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69  tly two hexadeci
239f0 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73  mal digits .** s
23a00 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74  pecifying an oct
23a10 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72  et value. ^Befor
23a20 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75  e the path or qu
23a30 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
23a40 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  f a.** URI filen
23a50 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65  ame are interpre
23a60 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e  ted, they are en
23a70 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
23a80 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65  8 and all .** he
23a90 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
23aa0 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61   sequences repla
23ab0 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ced by a single 
23ac0 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  byte containing 
23ad0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
23ae0 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74  ding octet. If t
23af0 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65  his process gene
23b00 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64  rates an invalid
23b10 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c   UTF-8 encoding,
23b20 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20  .** the results 
23b30 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
23b40 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
23b50 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
23b60 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
23b70 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
23b80 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
23b90 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
23ba0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
23bb0 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
23bc0 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
23bd0 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
23be0 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
23bf0 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
23c00 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
23c10 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
23c20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
23c30 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
23c40 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
23c50 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
23c60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
23c70 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
23c80 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c  en_v2()..**.** <
23c90 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
23ca0 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a  s Runtime users:
23cb0 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72  </b>  The tempor
23cc0 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75  ary directory mu
23cd0 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69  st be set.** pri
23ce0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71  or to calling sq
23cf0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
23d00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
23d10 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76  ).  Otherwise, v
23d20 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72  arious.** featur
23d30 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20  es that require 
23d40 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f  the use of tempo
23d50 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66  rary files may f
23d60 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ail..**.** See a
23d70 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65  lso: [sqlite3_te
23d80 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f  mp_directory].*/
23d90 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
23da0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
23db0 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
23dc0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
23dd0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
23de0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
23df0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
23e00 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
23e10 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
23e20 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
23e30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
23e40 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
23e50 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
23e60 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
23e70 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
23e80 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
23e90 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
23ea0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
23eb0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
23ec0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
23ed0 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
23ee0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
23ef0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
23f00 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
23f10 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
23f20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
23f30 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
23f40 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
23f50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
23f60 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
23f70 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
23f80 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
23f90 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
23fa0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
23fb0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
23fc0 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
23fd0 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
23fe0 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79  hese are utility
23ff0 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75   routines, usefu
24000 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65  l to VFS impleme
24010 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63  ntations, that c
24020 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69  heck.** to see i
24030 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
24040 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
24050 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
24060 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
24070 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
24080 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
24090 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71   value of that q
240a0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  uery parameter..
240b0 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68  **.** If F is th
240c0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  e database filen
240d0 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ame pointer pass
240e0 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
240f0 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a  n() method of .*
24100 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  * a VFS implemen
24110 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  tation when the 
24120 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
24130 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f  to xOpen() has o
24140 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f  ne or .** more o
24150 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
24160 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49  EN_URI] or [SQLI
24170 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
24180 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a   bits set and.**
24190 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f   P is the name o
241a0 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
241b0 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73  meter, then.** s
241c0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
241d0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
241e0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
241f0 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65  he P.** paramete
24200 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f  r if it exists o
24210 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
24220 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61   if P does not a
24230 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71  ppear as a .** q
24240 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
24250 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20  n F.  If P is a 
24260 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
24270 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65  of F.** has no e
24280 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74  xplicit value, t
24290 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
242a0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
242b0 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e  eturns.** a poin
242c0 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ter to an empty 
242d0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
242e0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
242f0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
24300 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61  tine assumes tha
24310 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  t P is a boolean
24320 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e  .** parameter an
24330 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  d returns true (
24340 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20  1) or false (0) 
24350 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
24360 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20   value.** of P. 
24370 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
24380 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
24390 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
243a0 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a  true (1) if the.
243b0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72  ** value of quer
243c0 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
243d0 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22   one of "yes", "
243e0 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69  true", or "on" i
243f0 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72  n any.** case or
24400 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
24410 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d  gins with a non-
24420 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68  zero number.  Th
24430 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  e .** sqlite3_ur
24440 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
24450 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
24460 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74  s false (0) if t
24470 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71  he value of.** q
24480 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
24490 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c   is one of "no",
244a0 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66   "false", or "of
244b0 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f  f" in any case o
244c0 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75  r.** if the valu
244d0 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
244e0 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49  numeric zero.  I
244f0 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65  f P is not a que
24500 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ry.** parameter 
24510 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76  on F or if the v
24520 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65  alue of P is doe
24530 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20  s not match any 
24540 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c  of the.** above,
24550 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
24560 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
24570 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e   returns (B!=0).
24580 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24590 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50  e3_uri_int64(F,P
245a0 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76  ,D) routine conv
245b0 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f  erts the value o
245c0 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34  f P into a.** 64
245d0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
245e0 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ger and returns 
245f0 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72  that integer, or
24600 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74   D if P does not
24610 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74  .** exist.  If t
24620 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
24630 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
24640 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72   than an integer
24650 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69  , then.** zero i
24660 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a  s returned..** .
24670 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c  ** If F is a NUL
24680 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
24690 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
246a0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
246b0 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73  ns NULL and.** s
246c0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
246d0 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
246e0 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f  s B.  If F is no
246f0 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  t a NULL pointer
24700 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61   and.** is not a
24710 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70   database file p
24720 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  athname pointer 
24730 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73  that SQLite pass
24740 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
24750 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c  n.** VFS method,
24760 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
24770 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  or of this routi
24780 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ne is undefined 
24790 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20  and probably.** 
247a0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a  undesirable..*/.
247b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
247c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75   char *sqlite3_u
247d0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
247e0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
247f0 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
24800 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f  zParam);.SQLITE_
24810 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
24820 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
24830 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
24840 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
24850 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
24860 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
24870 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
24880 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
24890 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
248a0 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
248b0 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
248c0 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
248d0 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
248e0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
248f0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
24900 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24910 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
24920 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
24930 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
24940 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
24950 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
24960 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
24970 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
24980 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
24990 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
249a0 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
249b0 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
249c0 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
249d0 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
249e0 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
249f0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
24a00 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
24a10 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
24a20 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65    ^The sqlite3_e
24a30 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
24a40 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
24a50 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
24a60 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
24a70 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
24a80 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
24a90 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
24aa0 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
24ab0 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
24ac0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
24ad0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
24ae0 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
24af0 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
24b00 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
24b10 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
24b20 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
24b30 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
24b40 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
24b50 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
24b60 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
24b70 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
24b80 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
24b90 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
24ba0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
24bb0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
24bc0 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
24bd0 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
24be0 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
24bf0 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
24c00 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
24c10 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
24c20 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
24c30 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
24c40 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
24c50 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
24c60 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
24c70 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
24c80 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24c90 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
24ca0 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
24cb0 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
24cc0 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
24cd0 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
24ce0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
24cf0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
24d00 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
24d10 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
24d20 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
24d30 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
24d40 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
24d50 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
24d60 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
24d70 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
24d80 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
24d90 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
24da0 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
24db0 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
24dc0 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
24dd0 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
24de0 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
24df0 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
24e00 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
24e10 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
24e20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
24e30 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
24e40 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
24e50 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
24e60 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
24e70 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
24e80 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
24e90 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
24ea0 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
24eb0 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
24ec0 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
24ed0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24ee0 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
24ef0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
24f00 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
24f10 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
24f20 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
24f30 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
24f40 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
24f50 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
24f60 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
24f70 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
24f80 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
24f90 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
24fa0 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
24fb0 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
24fc0 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
24fd0 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
24fe0 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
24ff0 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
25000 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
25010 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
25020 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
25030 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
25040 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
25050 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
25060 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
25070 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   set..*/.SQLITE_
25080 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
25090 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
250a0 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
250b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
250c0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
250d0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
250e0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
250f0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
25100 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  g(sqlite3*);.SQL
25110 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
25120 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
25130 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
25140 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
25150 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
25160 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
25170 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
25180 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
25190 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
251a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
251b0 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
251c0 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
251d0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
251e0 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
251f0 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
25200 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
25210 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
25220 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
25230 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
25240 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
25250 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
25260 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
25270 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
25280 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
25290 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
252a0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
252b0 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
252c0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
252d0 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
252e0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
252f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25300 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
25310 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
25320 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
25330 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
25340 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
25350 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
25360 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
25370 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
25380 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
25390 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
253a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
253b0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
253c0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
253d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
253e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
253f0 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
25400 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
25410 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
25420 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
25430 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
25440 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
25450 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
25460 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
25470 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
25480 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
25490 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
254a0 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
254b0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
254c0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
254d0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
254e0 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
254f0 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
25500 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
25510 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
25520 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
25530 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
25540 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
25550 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
25560 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
25570 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
25580 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
25590 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
255a0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
255b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
255c0 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
255d0 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
255e0 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
255f0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
25600 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
25610 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
25620 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
25630 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
25640 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
25650 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
25660 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
25670 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
25680 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
25690 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
256a0 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
256b0 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
256c0 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
256d0 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
256e0 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
256f0 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
25700 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
25710 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
25720 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
25730 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
25740 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
25750 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
25760 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
25770 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
25780 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
25790 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
257a0 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
257b0 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
257c0 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
257d0 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
257e0 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
257f0 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
25800 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
25810 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
25820 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
25830 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
25840 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
25850 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
25860 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
25870 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
25880 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
25890 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
258a0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
258b0 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
258c0 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
258d0 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
258e0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
258f0 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
25900 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
25910 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
25920 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
25930 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
25940 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
25950 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
25960 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
25970 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
25980 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
25990 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
259a0 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
259b0 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
259c0 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
259d0 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
259e0 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
259f0 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
25a00 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
25a10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
25a20 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
25a30 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
25a40 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
25a50 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
25a60 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
25a70 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
25a80 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
25a90 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
25aa0 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
25ab0 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
25ac0 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
25ad0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
25ae0 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
25af0 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
25b00 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
25b10 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
25b20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
25b30 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
25b40 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
25b50 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
25b60 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
25b70 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
25b80 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
25b90 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
25ba0 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
25bb0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
25bc0 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
25bd0 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
25be0 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
25bf0 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
25c00 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
25c10 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
25c20 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
25c30 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
25c40 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
25c50 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
25c60 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
25c70 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
25c80 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
25c90 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
25ca0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
25cb0 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
25cc0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d   int sqlite3_lim
25cd0 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
25ce0 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
25cf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25d00 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
25d10 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
25d20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
25d30 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
25d40 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
25d50 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
25d60 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
25d70 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
25d80 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
25d90 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
25da0 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
25db0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
25dc0 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
25dd0 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
25de0 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
25df0 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
25e00 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
25e10 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
25e20 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
25e30 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
25e40 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
25e50 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
25e60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
25e70 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
25e80 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
25e90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25ea0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
25eb0 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
25ec0 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
25ed0 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
25ee0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25ef0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
25f00 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25f10 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
25f20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25f30 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
25f40 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
25f50 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
25f60 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25f70 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
25f80 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  N]] ^(<dt>SQLITE
25f90 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
25fa0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25fb0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
25fc0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
25fd0 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
25fe0 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
25ff0 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
26000 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
26010 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
26020 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
26030 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
26040 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
26050 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
26060 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26070 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
26080 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
26090 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
260a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
260b0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
260c0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
260d0 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
260e0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
260f0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26100 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d  COMPOUND_SELECT]
26110 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26120 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
26130 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
26140 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
26150 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
26160 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
26170 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
26180 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
26190 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
261a0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
261b0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
261c0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
261d0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
261e0 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
261f0 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
26200 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
26210 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
26220 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
26230 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20    This limit is 
26240 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  not currently.**
26250 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67   enforced, thoug
26260 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  h that might be 
26270 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75  added in some fu
26280 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
26290 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29  ** SQLite.</dd>)
262a0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
262b0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
262c0 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ARG]] ^(<dt>SQLI
262d0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
262e0 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
262f0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
26300 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
26310 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
26320 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
26330 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
26340 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51  ACHED]] ^(<dt>SQ
26350 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
26360 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
26370 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
26380 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
26390 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
263a0 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
263b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
263c0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
263d0 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  NGTH]].** ^(<dt>
263e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
263f0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
26400 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26410 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
26420 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
26430 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
26440 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
26450 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
26460 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
26470 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
26480 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e  LE_NUMBER]].** ^
26490 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
264a0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
264b0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
264c0 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
264d0 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
264e0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
264f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
26500 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26510 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
26520 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
26530 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
26540 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
26550 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
26560 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
26570 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
26580 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
26590 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
265a0 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c  ER_THREADS]] ^(<
265b0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
265c0 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f  WORKER_THREADS</
265d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
265e0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
265f0 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65   auxiliary worke
26600 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20 61  r threads that a
26610 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70   single.** [prep
26620 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26630 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29  may start.</dd>)
26640 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ^.** </dl>.*/.#d
26650 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26660 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
26670 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
26680 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26690 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
266a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
266b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
266c0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
266d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
266e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
266f0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
26700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26710 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
26720 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
26730 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
26740 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
26750 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
26760 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26770 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
26780 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
26790 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
267a0 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
267b0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
267c0 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
267d0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
267e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
267f0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
26800 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
26810 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
26820 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
26830 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
26840 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
26850 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
26860 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
26870 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f   SQLITE_LIMIT_WO
26880 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20 20  RKER_THREADS    
26890 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a         11../*.**
268a0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
268b0 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
268c0 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  ement.** KEYWORD
268d0 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e  S: {SQL statemen
268e0 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a  t compiler}.**.*
268f0 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
26900 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75  SQL query, it mu
26910 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
26920 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
26930 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
26940 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
26950 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
26960 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
26970 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73  gument, "db", is
26980 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
26990 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65  nection] obtaine
269a0 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f  d from a.** prio
269b0 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
269c0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
269d0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
269e0 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  open_v2()] or.**
269f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
26a00 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61  ()].  The databa
26a10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
26a20 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e  st not have been
26a30 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
26a40 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
26a50 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
26a60 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
26a70 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
26a80 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
26a90 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
26aa0 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
26ab0 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
26ac0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
26ad0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
26ae0 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
26af0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26b00 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
26b10 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
26b20 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
26b30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74  .** ^If the nByt
26b40 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65  e argument is le
26b50 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ss than zero, th
26b60 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
26b70 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
26b80 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
26b90 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
26ba0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
26bb0 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61  hen it is the ma
26bc0 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20  ximum.** number 
26bd0 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66  of  bytes read f
26be0 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e  rom zSql.  ^When
26bf0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
26c00 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a  gative, the.** z
26c10 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20  Sql string ends 
26c20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69  at either the fi
26c30 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c  rst '\000' or '\
26c40 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72  u0000' character
26c50 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65   or.** the nByte
26c60 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65  -th byte, whiche
26c70 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
26c80 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
26c90 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  nows.** that the
26ca0 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
26cb0 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
26cc0 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69  ed, then there i
26cd0 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72  s a small.** per
26ce0 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
26cf0 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20  ge to be gained 
26d00 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  by passing an nB
26d10 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
26d20 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74  at.** is equal t
26d30 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  o the number of 
26d40 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
26d50 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
26d60 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
26d70 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
26d80 20 62 79 74 65 73 20 61 73 20 74 68 69 73 20 73   bytes as this s
26d90 61 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d  aves SQLite from
26da0 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61   having to.** ma
26db0 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ke a copy of the
26dc0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a   input string..*
26dd0 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20  *.** ^If pzTail 
26de0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
26df0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
26e00 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
26e10 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70   first byte.** p
26e20 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
26e30 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
26e40 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
26e50 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
26e60 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20  only.** compile 
26e70 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
26e80 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
26e90 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
26ea0 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77  pointing to.** w
26eb0 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
26ec0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a  mpiled..**.** ^*
26ed0 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
26ee0 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
26ef0 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
26f00 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
26f10 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
26f20 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
26f30 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20  3_step()].  ^If 
26f40 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
26f50 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
26f60 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e  t.** to NULL.  ^
26f70 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
26f80 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
26f90 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
26fa0 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73  is an empty.** s
26fb0 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
26fc0 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
26fd0 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
26fe0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  .** The calling 
26ff0 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
27000 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
27010 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
27020 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
27030 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
27040 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
27050 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
27060 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
27070 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20   ppStmt may not 
27080 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
27090 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20  On success, the 
270a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
270b0 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74  ) family of rout
270c0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
270d0 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65  ITE_OK];.** othe
270e0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
270f0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
27100 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
27110 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
27120 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
27130 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
27140 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
27150 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
27160 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
27170 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
27180 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
27190 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
271a0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
271b0 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
271c0 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
271d0 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ged..** ^In the 
271e0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
271f0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
27200 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
27210 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
27220 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
27230 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
27240 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
27250 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
27260 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
27270 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
27280 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
27290 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66  to.** behave dif
272a0 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65  ferently in thre
272b0 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e ways:.**.** <o
272c0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  l>.** <li>.** ^I
272d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
272e0 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
272f0 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
27300 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
27310 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
27320 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
27330 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
27340 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
27350 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
27360 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
27370 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
27380 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d  n it again. As m
27390 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d  any as [SQLITE_M
273a0 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d  AX_SCHEMA_RETRY]
273b0 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c  .** retries will
273c0 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71   occur before sq
273d0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76  lite3_step() giv
273e0 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e  es up and return
273f0 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c  s an error..** <
27400 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
27410 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
27420 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
27430 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
27440 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
27450 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
27460 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
27470 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
27480 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
27490 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
274a0 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
274b0 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
274c0 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
274d0 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
274e0 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
274f0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c  .** and the appl
27500 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61  ication would ha
27510 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
27520 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
27530 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
27540 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
27550 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
27560 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
27570 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
27580 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
27590 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
275a0 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
275b0 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
275c0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
275d0 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
275e0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
275f0 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63  ^If the specific
27600 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20   value bound to 
27610 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73  [parameter | hos
27620 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  t parameter] in 
27630 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c  the .** WHERE cl
27640 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75  ause might influ
27650 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20  ence the choice 
27660 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f  of query plan fo
27670 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a  r a statement,.*
27680 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  * then the state
27690 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74  ment will be aut
276a0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
276b0 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65  piled, as if the
276c0 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20  re had been .** 
276d0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c  a schema change,
276e0 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b   on the first  [
276f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27700 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  call following a
27710 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20  ny change.** to 
27720 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
27730 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67  d_text | binding
27740 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61  s] of that [para
27750 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65  meter]. .** ^The
27760 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
27770 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20  of WHERE-clause 
27780 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68  [parameter] migh
27790 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
277a0 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75  .** choice of qu
277b0 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20  ery plan if the 
277c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
277d0 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
277e0 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f  of a [LIKE].** o
277f0 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  r [GLOB] operato
27800 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61  r or if the para
27810 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65  meter is compare
27820 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20  d to an indexed 
27830 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68  column.** and th
27840 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
27850 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d  _STAT3] compile-
27860 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
27870 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e  nabled..** </li>
27880 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c  .** </ol>.*/.SQL
27890 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
278a0 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
278b0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
278c0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
278d0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
278e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
278f0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
27900 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
27910 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
27920 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
27930 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
27940 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
27950 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
27960 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
27970 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
27980 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
27990 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
279a0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
279b0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
279c0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
279d0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
279e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
279f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
27a00 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
27a10 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
27a20 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
27a30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
27a40 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
27a50 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
27a60 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
27a70 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
27a80 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
27a90 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
27aa0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
27ab0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
27ac0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
27ad0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
27ae0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
27af0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
27b00 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
27b10 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
27b20 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
27b30 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
27b40 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
27b50 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
27b60 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
27b70 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
27b80 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
27b90 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
27ba0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
27bb0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
27bc0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
27bd0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
27be0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
27bf0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
27c00 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
27c10 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
27c20 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
27c30 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
27c40 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
27c50 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
27c60 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
27c70 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c  f zSql */.);.SQL
27c80 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
27c90 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
27ca0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
27cb0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
27cc0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
27cd0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
27ce0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
27cf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
27d00 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
27d10 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
27d20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
27d30 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
27d40 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
27d50 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
27d60 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
27d70 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
27d80 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
27d90 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
27da0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
27db0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
27dc0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
27dd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27de0 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
27df0 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a  tement SQL.**.**
27e00 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
27e10 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
27e20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
27e30 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
27e40 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
27e50 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
27e60 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
27e70 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20  tement] if that 
27e80 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
27e90 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
27ea0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
27eb0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
27ec0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27ed0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51  e16_v2()]..*/.SQ
27ee0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
27ef0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
27f00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
27f10 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
27f20 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
27f30 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
27f40 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
27f50 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20   Database.**.** 
27f60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
27f70 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e  t_readonly(X) in
27f80 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27f90 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
27fa0 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69  if.** and only i
27fb0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
27fc0 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b  statement] X mak
27fd0 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61  es no direct cha
27fe0 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63  nges to.** the c
27ff0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
28000 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
28010 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70  ** Note that [ap
28020 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
28030 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
28040 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20   or.** [virtual 
28050 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68  tables] might ch
28060 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
28070 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20  e indirectly as 
28080 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20  a side effect.  
28090 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
280a0 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  e, if an applica
280b0 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66  tion defines a f
280c0 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22  unction "eval()"
280d0 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20   that .** calls 
280e0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
280f0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f  , then the follo
28100 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  wing SQL stateme
28110 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e  nt would.** chan
28120 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
28130 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64  file through sid
28140 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a  e-effects:.**.**
28150 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
28160 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20  e>.**    SELECT 
28170 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f  eval('DELETE FRO
28180 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a  M t1') FROM t2;.
28190 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
281a0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74  quote>.**.** But
281b0 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45   because the [SE
281c0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
281d0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
281e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
281f0 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73  e.** directly, s
28200 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
28210 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69  only() would sti
28220 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29  ll return true.)
28230 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63  ^.**.** ^Transac
28240 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61  tion control sta
28250 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20  tements such as 
28260 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54  [BEGIN], [COMMIT
28270 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a  ], [ROLLBACK],.*
28280 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61  * [SAVEPOINT], a
28290 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75  nd [RELEASE] cau
282a0 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  se sqlite3_stmt_
282b0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
282c0 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69  turn true,.** si
282d0 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  nce the statemen
282e0 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  ts themselves do
282f0 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f   not actually mo
28300 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
28310 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20  e but.** rather 
28320 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65  they control the
28330 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20   timing of when 
28340 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73  other statements
28350 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20   modify the .** 
28360 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20  database.  ^The 
28370 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45  [ATTACH] and [DE
28380 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73  TACH] statements
28390 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73   also cause.** s
283a0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
283b0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
283c0 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69   true since, whi
283d0 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65  le those stateme
283e0 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  nts.** change th
283f0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
28400 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  of a database co
28410 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64  nnection, they d
28420 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63  o not make .** c
28430 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
28440 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
28450 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64  abase files on d
28460 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  isk..*/.SQLITE_A
28470 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
28480 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  tmt_readonly(sql
28490 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
284a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
284b0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
284c0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
284d0 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52  ement Has Been R
284e0 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eset.**.** ^The 
284f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
28500 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(S) interface r
28510 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
28520 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a  -zero) if the.**
28530 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28540 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e  ment] S has been
28550 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73   stepped at leas
28560 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a  t once using .**
28570 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
28580 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72  )] but has not r
28590 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
285a0 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20   and/or has not 
285b0 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75  .** been reset u
285c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
285d0 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73  set(S)].  ^The s
285e0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
285f0 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  (S).** interface
28600 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69   returns false i
28610 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f S is a NULL po
28620 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20  inter.  If S is 
28630 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70  not a .** NULL p
28640 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f  ointer and is no
28650 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
28660 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64   valid [prepared
28670 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
28680 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  bject, then the 
28690 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
286a0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
286b0 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
286c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
286d0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
286e0 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20   in combination 
286f0 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
28700 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61  mt()].** to loca
28710 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20  te all prepared 
28720 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
28730 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74  iated with a dat
28740 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63  abase .** connec
28750 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e  tion that are in
28760 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72   need of being r
28770 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20  eset.  This can 
28780 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20  be used,.** for 
28790 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67  example, in diag
287a0 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20  nostic routines 
287b0 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72  to search for pr
287c0 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65  epared .** state
287d0 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68  ments that are h
287e0 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63  olding a transac
287f0 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51  tion open..*/.SQ
28800 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28810 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
28820 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
28830 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28840 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
28850 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
28860 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
28870 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28880 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
28890 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
288a0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
288b0 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
288c0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
288d0 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
288e0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
288f0 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
28900 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
28910 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
28920 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
28930 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
28940 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
28950 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
28960 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
28970 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
28980 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
28990 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
289a0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
289b0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
289c0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
289d0 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
289e0 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
289f0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
28a00 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
28a10 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
28a20 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28a30 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
28a40 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
28a50 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
28a60 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
28a70 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
28a80 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
28a90 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
28aa0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
28ab0 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
28ac0 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
28ad0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
28ae0 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
28af0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28b00 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
28b10 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
28b20 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
28b30 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
28b40 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
28b50 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
28b60 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
28b70 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
28b80 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
28b90 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28ba0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
28bb0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
28bc0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
28bd0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28be0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
28bf0 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
28c00 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
28c10 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
28c20 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
28c30 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
28c40 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
28c50 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
28c60 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
28c70 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
28c80 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
28c90 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
28ca0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
28cb0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
28cc0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
28cd0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
28ce0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
28cf0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
28d00 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
28d10 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
28d20 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
28d30 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
28d40 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
28d50 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
28d60 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
28d70 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
28d80 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
28d90 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
28da0 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
28db0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
28dc0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
28dd0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
28de0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
28df0 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
28e00 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
28e10 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
28e20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
28e30 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
28e40 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
28e50 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
28e60 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
28e70 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
28e80 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
28e90 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
28ea0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
28eb0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
28ec0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
28ed0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
28ee0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
28ef0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
28f00 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
28f10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28f20 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
28f30 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
28f40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
28f50 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
28f60 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
28f70 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
28f80 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
28f90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
28fa0 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
28fb0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
28fc0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
28fd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28fe0 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
28ff0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
29000 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
29010 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
29020 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
29030 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
29040 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
29050 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
29060 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
29070 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
29080 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
29090 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
290a0 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
290b0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
290c0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
290d0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
290e0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
290f0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
29100 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
29110 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29120 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
29130 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
29140 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
29150 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
29160 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
29170 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
29180 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
29190 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
291a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
291b0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
291c0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
291d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
291e0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
291f0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
29200 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
29210 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
29220 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
29230 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
29240 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
29250 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
29260 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29270 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
29280 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
29290 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
292a0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
292b0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
292c0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
292d0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
292e0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
292f0 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
29300 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
29310 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
29320 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
29330 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
29340 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
29350 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
29360 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
29370 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
29380 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
29390 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
293a0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
293b0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
293c0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
293d0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
293e0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
293f0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
29400 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
29410 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
29420 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
29430 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
29440 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
29450 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
29460 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
29470 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
29480 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
29490 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
294a0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
294b0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
294c0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
294d0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
294e0 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
294f0 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
29500 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
29510 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
29520 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
29530 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
29540 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
29550 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
29560 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
29570 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
29580 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
29590 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
295a0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
295b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
295c0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
295d0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
295e0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
295f0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
29600 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
29610 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
29620 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
29630 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
29640 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
29650 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
29660 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
29670 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
29680 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
29690 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
296a0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
296b0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
296c0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
296d0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
296e0 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
296f0 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
29700 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
29710 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
29720 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
29730 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29740 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
29750 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
29760 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
29770 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
29780 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
29790 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
297a0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
297b0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
297c0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
297d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
297e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
297f0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
29800 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
29810 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
29820 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
29830 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
29840 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
29850 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
29860 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
29870 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
29880 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
29890 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
298a0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
298b0 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55  d_blob() is a NU
298c0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
298d0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
298e0 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72  eter.** is ignor
298f0 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72  ed and the end r
29900 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d  esult is the sam
29910 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e  e as sqlite3_bin
29920 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20  d_null()..**.** 
29930 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
29940 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
29950 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
29960 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
29970 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
29980 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
29990 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
299a0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
299b0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
299c0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
299d0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
299e0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
299f0 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
29a00 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
29a10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
29a20 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
29a30 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
29a40 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20  _text16().** is 
29a50 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
29a60 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
29a70 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
29a80 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
29a90 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
29aa0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
29ab0 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  r..** If the fou
29ac0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
29ad0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
29ae0 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  ob() is negative
29af0 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65  , then.** the be
29b00 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
29b10 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  ned..** If a non
29b20 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
29b30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
29b40 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
29b50 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
29b60 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
29b70 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c  _text16() or sql
29b80 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
29b90 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20  () then.** that 
29ba0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
29bb0 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
29bc0 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
29bd0 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
29be0 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
29bf0 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
29c00 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
29c10 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
29c20 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
29c30 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
29c40 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
29c50 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
29c60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
29c70 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
29c80 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
29c90 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
29ca0 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
29cb0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
29cc0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
29cd0 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
29ce0 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
29cf0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
29d00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
29d10 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
29d20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72  the BLOB and str
29d30 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65  ing binding inte
29d40 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64  rfaces.** is a d
29d50 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
29d60 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
29d70 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
29d80 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
29d90 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
29da0 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
29db0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
29dc0 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
29dd0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
29de0 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
29df0 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50   call to bind AP
29e00 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20  I fails..** ^If 
29e10 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
29e20 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
29e30 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
29e40 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
29e50 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
29e60 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
29e70 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
29e80 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
29e90 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
29ea0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
29eb0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
29ec0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
29ed0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
29ee0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
29ef0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
29f00 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
29f10 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
29f20 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
29f30 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
29f40 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
29f50 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
29f60 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
29f70 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
29f80 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
29f90 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f  xt64() must be o
29fa0 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45  ne of.** [SQLITE
29fb0 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
29fc0 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
29fd0 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
29fe0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a  LITE_UTF16LE].**
29ff0 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
2a000 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
2a010 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72  text in the thir
2a020 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  d parameter.  If
2a030 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72  .** the sixth ar
2a040 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2a050 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2a060 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
2a070 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c  e.** allowed val
2a080 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c  ues shown above,
2a090 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20   or if the text 
2a0a0 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
2a0b0 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68  erent.** from th
2a0c0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
2a0d0 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74  fied by the sixt
2a0e0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  h parameter, the
2a0f0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
2a100 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
2a110 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a120 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2a130 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
2a140 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
2a150 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
2a160 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
2a170 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
2a180 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
2a190 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
2a1a0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
2a1b0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
2a1c0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
2a1d0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
2a1e0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
2a1f0 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
2a200 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
2a210 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
2a220 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
2a230 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
2a240 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2a250 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
2a260 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
2a270 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
2a280 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
2a290 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
2a2a0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
2a2b0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
2a2c0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
2a2d0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
2a2e0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2a2f0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
2a300 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
2a310 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
2a320 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a330 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
2a340 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
2a350 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
2a360 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2a370 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
2a380 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
2a390 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2a3a0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
2a3b0 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
2a3c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2a3d0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
2a3e0 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
2a3f0 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
2a400 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a410 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
2a420 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
2a430 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
2a440 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2a450 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
2a460 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
2a470 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
2a480 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
2a490 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
2a4a0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
2a4b0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
2a4c0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
2a4d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a4e0 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
2a4f0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
2a500 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
2a510 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
2a520 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
2a530 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
2a540 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49  * ^[SQLITE_TOOBI
2a550 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  G] might be retu
2a560 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65  rned if the size
2a570 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20   of a string or 
2a580 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20  BLOB.** exceeds 
2a590 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62  limits imposed b
2a5a0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
2a5b0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
2a5c0 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b  LENGTH]) or.** [
2a5d0 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54  SQLITE_MAX_LENGT
2a5e0 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  H]..** ^[SQLITE_
2a5f0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
2a600 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
2a610 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
2a620 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
2a630 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
2a640 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
2a650 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
2a660 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2a670 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a680 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
2a690 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2a6a0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2a6b0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
2a6c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2a6d0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
2a6e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2a6f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
2a700 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a710 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2a720 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
2a730 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
2a740 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2a750 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  nd_blob64(sqlite
2a760 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2a770 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74  nst void*, sqlit
2a780 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2a790 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a7a0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2a7b0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
2a7c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2a7d0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2a7e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
2a7f0 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  e);.SQLITE_API i
2a800 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2a810 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2a820 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51  *, int, int);.SQ
2a830 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2a840 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
2a850 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a860 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
2a870 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  4);.SQLITE_API i
2a880 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2a890 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
2a8a0 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
2a8b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2a8c0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
2a8d0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e  e3_stmt*,int,con
2a8e0 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69  st char*,int,voi
2a8f0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
2a900 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2a910 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2a920 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a930 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2a940 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2a950 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2a960 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2a970 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74  ind_text64(sqlit
2a980 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2a990 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
2a9a0 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
2a9b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a9c0 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
2a9d0 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68  d*), unsigned ch
2a9e0 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51  ar encoding);.SQ
2a9f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2aa00 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2aa10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2aa20 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
2aa30 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2aa40 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2aa50 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
2aa60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2aa70 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
2aa80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2aa90 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
2aaa0 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  eters.**.** ^Thi
2aab0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
2aac0 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
2aad0 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
2aae0 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
2aaf0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
2ab00 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
2ab10 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
2ab20 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
2ab30 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
2ab40 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
2ab50 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
2ab60 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
2ab70 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
2ab80 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
2ab90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2aba0 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
2abb0 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
2abc0 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
2abd0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
2abe0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
2abf0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
2ac00 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
2ac10 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
2ac20 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
2ac30 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
2ac40 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
2ac50 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
2ac60 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
2ac70 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
2ac80 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
2ac90 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
2aca0 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
2acb0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
2acc0 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
2acd0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2ace0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2acf0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2ad00 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2ad10 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2ad20 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
2ad30 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ad40 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2ad50 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2ad60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2ad70 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
2ad80 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2ad90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2ada0 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
2adb0 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
2adc0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2add0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
2ade0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
2adf0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
2ae00 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
2ae10 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
2ae20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2ae30 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2ae40 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
2ae50 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
2ae60 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2ae70 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2ae80 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
2ae90 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
2aea0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
2aeb0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2aec0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
2aed0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
2aee0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2aef0 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
2af00 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
2af10 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
2af20 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
2af30 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
2af40 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2af50 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
2af60 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
2af70 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
2af80 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
2af90 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
2afa0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
2afb0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
2afc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2afd0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
2afe0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2aff0 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
2b000 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
2b010 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2b020 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
2b030 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
2b040 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
2b050 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2b060 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2b070 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
2b080 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
2b090 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
2b0a0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
2b0b0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
2b0c0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
2b0d0 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
2b0e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2b0f0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2b100 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2b110 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2b120 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2b130 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2b140 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2b150 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2b160 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2b170 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2b180 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2b190 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
2b1a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2b1b0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2b1c0 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
2b1d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
2b1e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
2b1f0 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
2b200 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
2b210 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   Name.**.** ^Ret
2b220 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
2b230 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
2b240 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
2b250 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
2b260 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2b270 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
2b280 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
2b290 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
2b2a0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
2b2b0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2b2c0 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
2b2d0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
2b2e0 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
2b2f0 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
2b300 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
2b310 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
2b320 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
2b330 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
2b340 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
2b350 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
2b360 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
2b370 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
2b380 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
2b390 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2b3a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2b3b0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2b3c0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2b3d0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2b3e0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
2b3f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2b400 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2b410 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2b420 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2b430 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2b440 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b450 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2b460 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
2b470 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
2b480 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
2b490 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2b4a0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
2b4b0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
2b4c0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
2b4d0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
2b4e0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
2b4f0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2b500 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
2b510 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2b520 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2b530 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
2b540 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
2b550 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
2b560 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45   NULL..*/.SQLITE
2b570 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2b580 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2b590 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2b5a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b5b0 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
2b5c0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
2b5d0 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  et.**.** ^Return
2b5e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2b5f0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2b600 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
2b610 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
2b620 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b630 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
2b640 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
2b650 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
2b660 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
2b670 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
2b680 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
2b690 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
2b6a0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2b6b0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2b6c0 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
2b6d0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2b6e0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
2b6f0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2b700 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b710 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
2b720 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2b730 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2b740 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2b750 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
2b760 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
2b770 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
2b780 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
2b790 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2b7a0 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
2b7b0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2b7c0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2b7d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2b7e0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2b7f0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
2b800 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
2b810 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2b820 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2b830 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2b840 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
2b850 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2b860 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2b870 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
2b880 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
2b890 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2b8a0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2b8b0 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
2b8c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2b8d0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
2b8e0 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
2b8f0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
2b900 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
2b910 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2b920 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
2b930 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
2b940 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2b950 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
2b960 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
2b970 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2b980 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2b990 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2b9a0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2b9b0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2b9c0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2b9d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2b9e0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2b9f0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2ba00 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
2ba10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2ba20 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
2ba30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2ba40 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
2ba50 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2ba60 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
2ba70 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
2ba80 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
2ba90 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
2baa0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
2bab0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
2bac0 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
2bad0 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
2bae0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
2baf0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2bb00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
2bb10 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
2bb20 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
2bb30 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
2bb40 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
2bb50 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
2bb60 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
2bb70 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
2bb80 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
2bb90 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
2bba0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
2bbb0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
2bbc0 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
2bbd0 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
2bbe0 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
2bbf0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
2bc00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2bc10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2bc20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2bc30 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
2bc40 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2bc50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2bc60 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2bc70 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
2bc80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
2bc90 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
2bca0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2bcb0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2bcc0 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
2bcd0 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
2bce0 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
2bcf0 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
2bd00 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
2bd10 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
2bd20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
2bd30 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
2bd40 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2bd50 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
2bd60 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2bd70 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
2bd80 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
2bd90 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
2bda0 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
2bdb0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2bdc0 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
2bdd0 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
2bde0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
2bdf0 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
2be00 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2be10 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
2be20 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
2be30 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2be40 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
2be50 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
2be60 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
2be70 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
2be80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2be90 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
2bea0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2beb0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2bec0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2bed0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2bee0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2bef0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2bf00 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2bf10 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2bf20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2bf30 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
2bf40 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
2bf50 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
2bf60 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
2bf70 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
2bf80 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
2bf90 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
2bfa0 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
2bfb0 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
2bfc0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
2bfd0 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
2bfe0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2bff0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2c000 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
2c010 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2c020 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
2c030 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2c040 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2c050 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
2c060 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
2c070 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
2c080 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
2c090 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
2c0a0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
2c0b0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
2c0c0 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
2c0d0 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
2c0e0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
2c0f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
2c100 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2c110 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
2c120 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
2c130 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
2c140 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
2c150 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
2c160 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
2c170 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
2c180 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
2c190 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
2c1a0 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
2c1b0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2c1c0 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
2c1d0 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
2c1e0 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
2c1f0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2c200 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2c210 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
2c220 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
2c230 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
2c240 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
2c250 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
2c260 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
2c270 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
2c280 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
2c290 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
2c2a0 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
2c2b0 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
2c2c0 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
2c2d0 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
2c2e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
2c2f0 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
2c300 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
2c310 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
2c320 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
2c330 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
2c340 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
2c350 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
2c360 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
2c370 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2c380 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2c390 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
2c3a0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
2c3b0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
2c3c0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
2c3d0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
2c3e0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
2c3f0 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
2c400 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2c410 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2c420 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2c430 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
2c440 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2c450 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
2c460 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
2c470 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
2c480 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
2c490 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
2c4a0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
2c4b0 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
2c4c0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2c4d0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2c4e0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
2c4f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2c500 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2c510 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
2c520 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2c530 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2c540 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2c550 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2c560 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2c570 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2c580 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
2c590 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2c5a0 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
2c5b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2c5c0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2c5d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2c5e0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
2c5f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2c600 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2c610 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2c620 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
2c630 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2c640 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2c650 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2c660 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2c670 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
2c680 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2c690 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c6a0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
2c6b0 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
2c6c0 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  Result.**.** ^(T
2c6d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2c6e0 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
2c6f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2c700 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
2c710 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
2c720 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2c730 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2c740 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
2c750 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
2c760 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
2c770 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
2c780 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
2c790 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2c7a0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
2c7b0 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
2c7c0 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
2c7d0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
2c7e0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2c7f0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2c800 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
2c810 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2c820 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
2c830 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2c840 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
2c850 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2c860 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
2c870 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
2c880 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
2c890 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2c8a0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
2c8b0 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
2c8c0 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
2c8d0 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
2c8e0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
2c8f0 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
2c900 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
2c910 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
2c920 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
2c930 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
2c940 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
2c950 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
2c960 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
2c970 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
2c980 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
2c990 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
2c9a0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
2c9b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2c9c0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
2c9d0 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
2c9e0 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
2c9f0 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
2ca00 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
2ca10 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
2ca20 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
2ca30 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
2ca40 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
2ca50 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
2ca60 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
2ca70 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
2ca80 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
2ca90 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
2caa0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
2cab0 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
2cac0 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
2cad0 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
2cae0 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
2caf0 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
2cb00 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
2cb10 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
2cb20 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2cb30 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2cb40 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2cb50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2cb60 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2cb70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2cb80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2cb90 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
2cba0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2cbb0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
2cbc0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
2cbd0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
2cbe0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2cbf0 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
2cc00 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2cc10 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2cc20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2cc30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2cc40 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2cc50 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
2cc60 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
2cc70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2cc80 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2cc90 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
2cca0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
2ccb0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
2ccc0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2ccd0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
2cce0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2ccf0 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
2cd00 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2cd10 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2cd20 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
2cd30 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
2cd40 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
2cd50 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
2cd60 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
2cd70 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
2cd80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2cd90 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2cda0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2cdb0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
2cdc0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2cdd0 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
2cde0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2cdf0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2ce00 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
2ce10 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
2ce20 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2ce30 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
2ce40 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
2ce50 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2ce60 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
2ce70 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
2ce80 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
2ce90 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2cea0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
2ceb0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
2cec0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
2ced0 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
2cee0 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
2cef0 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
2cf00 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
2cf10 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
2cf20 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2cf30 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
2cf40 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
2cf50 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
2cf60 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2cf70 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
2cf80 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
2cf90 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2cfa0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
2cfb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2cfc0 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
2cfd0 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
2cfe0 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
2cff0 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
2d000 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
2d010 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2d020 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
2d030 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
2d040 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
2d050 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
2d060 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
2d070 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
2d080 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2d090 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
2d0a0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
2d0b0 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
2d0c0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2d0d0 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
2d0e0 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
2d0f0 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
2d100 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
2d110 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
2d120 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
2d130 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2d140 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2d150 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
2d160 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
2d170 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2d180 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2d190 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
2d1a0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
2d1b0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
2d1c0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2d1d0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2d1e0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2d1f0 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
2d200 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
2d210 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
2d220 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
2d230 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
2d240 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
2d250 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
2d260 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
2d270 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
2d280 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
2d290 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
2d2a0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
2d2b0 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
2d2c0 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
2d2d0 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
2d2e0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2d2f0 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
2d300 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
2d310 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
2d320 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
2d330 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
2d340 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
2d350 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
2d360 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
2d370 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
2d380 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
2d390 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
2d3a0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2d3b0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2d3c0 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
2d3d0 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
2d3e0 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
2d3f0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2d400 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
2d410 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
2d420 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2d430 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
2d440 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
2d450 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
2d460 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
2d470 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
2d480 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
2d490 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
2d4a0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
2d4b0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
2d4c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d4d0 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
2d4e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2d4f0 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
2d500 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
2d510 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2d520 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
2d530 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
2d540 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2d550 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
2d560 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
2d570 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
2d580 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
2d590 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
2d5a0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
2d5b0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
2d5c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d5d0 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
2d5e0 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
2d5f0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
2d600 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
2d610 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
2d620 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
2d630 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
2d640 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
2d650 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
2d660 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
2d670 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
2d680 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d690 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
2d6a0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
2d6b0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
2d6c0 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
2d6d0 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
2d6e0 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
2d6f0 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
2d700 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
2d710 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
2d720 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2d730 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
2d740 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2d750 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
2d760 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
2d770 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2d780 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
2d790 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2d7a0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
2d7b0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
2d7c0 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
2d7d0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2d7e0 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
2d7f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d800 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
2d810 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
2d820 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
2d830 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2d840 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
2d850 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
2d860 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
2d870 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
2d880 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d890 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
2d8a0 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
2d8b0 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
2d8c0 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
2d8d0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2d8e0 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
2d8f0 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
2d900 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
2d910 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
2d920 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
2d930 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
2d940 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
2d950 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
2d960 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
2d970 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2d980 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
2d990 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
2d9a0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
2d9b0 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
2d9c0 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
2d9d0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
2d9e0 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
2d9f0 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
2da00 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
2da10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
2da20 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
2da30 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
2da40 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
2da50 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
2da60 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
2da70 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2da80 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
2da90 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2daa0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
2dab0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2dac0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2dad0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
2dae0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
2daf0 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
2db00 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2db10 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
2db20 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
2db30 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
2db40 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
2db50 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
2db60 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
2db70 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
2db80 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2db90 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
2dba0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
2dbb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
2dbc0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
2dbd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2dbe0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2dbf0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2dc00 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
2dc10 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
2dc20 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2dc30 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2dc40 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
2dc50 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
2dc60 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
2dc70 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
2dc80 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2dc90 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
2dca0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
2dcb0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
2dcc0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2dcd0 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ended..*/.SQLITE
2dce0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2dcf0 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
2dd00 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2dd10 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
2dd20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
2dd30 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult set.**.** ^
2dd40 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2dd50 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
2dd60 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
2dd70 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2dd80 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
2dd90 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
2dda0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
2ddb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ddc0 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
2ddd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
2dde0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
2ddf0 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
2de00 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
2de10 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
2de20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
2de30 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
2de40 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
2de50 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
2de60 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2de70 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
2de80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2de90 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2dea0 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
2deb0 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
2dec0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
2ded0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2dee0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
2def0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
2df00 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
2df10 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
2df20 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
2df30 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2df40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2df50 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
2df60 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
2df70 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
2df80 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2df90 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
2dfa0 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
2dfb0 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
2dfc0 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
2dfd0 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
2dfe0 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
2dff0 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
2e000 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
2e010 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
2e020 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
2e030 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
2e040 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
2e050 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2e060 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
2e070 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51  n_count()].*/.SQ
2e080 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2e090 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2e0a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2e0b0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2e0c0 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
2e0d0 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
2e0e0 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
2e0f0 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
2e100 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
2e110 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
2e120 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
2e130 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
2e140 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
2e150 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2e160 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
2e170 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
2e180 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
2e190 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
2e1a0 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
2e1b0 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
2e1c0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
2e1d0 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
2e1e0 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
2e1f0 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
2e200 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
2e210 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
2e220 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
2e230 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
2e240 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
2e250 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
2e260 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
2e270 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
2e280 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
2e290 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
2e2a0 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
2e2b0 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
2e2c0 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
2e2d0 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
2e2e0 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
2e2f0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
2e300 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2e310 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
2e320 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
2e330 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2e340 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
2e350 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
2e360 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
2e370 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
2e380 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
2e390 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
2e3a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
2e3b0 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
2e3c0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
2e3d0 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
2e3e0 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
2e3f0 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
2e400 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
2e410 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2e420 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
2e430 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
2e440 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
2e450 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2e460 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2e470 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
2e480 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
2e490 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
2e4a0 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
2e4b0 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2e4c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2e4d0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2e4e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2e4f0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2e500 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2e510 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2e520 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2e530 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2e540 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e550 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2e560 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2e570 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2e580 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2e590 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2e5a0 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2e5b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2e5c0 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2e5d0 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
2e5e0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2e5f0 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2e600 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
2e610 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2e620 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2e630 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
2e640 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
2e650 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2e660 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
2e670 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2e680 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
2e690 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
2e6a0 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
2e6b0 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
2e6c0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2e6d0 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
2e6e0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
2e6f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2e700 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
2e710 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
2e720 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2e730 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2e740 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2e750 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2e760 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
2e770 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e780 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
2e790 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
2e7a0 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
2e7b0 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
2e7c0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2e7d0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2e7e0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
2e7f0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2e800 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e810 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
2e820 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2e830 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
2e840 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2e850 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
2e860 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2e870 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2e880 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2e890 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2e8a0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2e8b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
2e8c0 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
2e8d0 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
2e8e0 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
2e8f0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2e900 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
2e910 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2e920 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2e930 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e940 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2e950 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2e960 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
2e970 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2e980 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
2e990 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
2e9a0 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
2e9b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
2e9c0 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
2e9d0 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
2e9e0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
2e9f0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2ea00 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2ea10 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
2ea20 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
2ea30 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
2ea40 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2ea50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2ea60 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
2ea70 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
2ea80 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
2ea90 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
2eaa0 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
2eab0 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
2eac0 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
2ead0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2eae0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2eaf0 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
2eb00 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
2eb10 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
2eb20 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
2eb30 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2eb40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2eb50 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
2eb60 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
2eb70 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
2eb80 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2eb90 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2eba0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2ebb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ebc0 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2ebd0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2ebe0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2ebf0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2ec00 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2ec10 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
2ec20 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
2ec30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ec40 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
2ec50 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2ec60 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
2ec70 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2ec80 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2ec90 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2eca0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2ecb0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2ecc0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2ecd0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2ece0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2ecf0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2ed00 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2ed10 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2ed20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2ed30 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2ed40 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2ed50 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2ed60 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2ed70 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
2ed80 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2ed90 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2eda0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2edb0 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
2edc0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2edd0 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
2ede0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2edf0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2ee00 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2ee10 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2ee20 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2ee30 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
2ee40 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2ee50 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
2ee60 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2ee70 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
2ee80 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2ee90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2eea0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2eeb0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2eec0 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2eed0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2eee0 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
2eef0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2ef00 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2ef10 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2ef20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
2ef30 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2ef40 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2ef50 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2ef60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2ef70 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2ef80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ef90 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
2efa0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
2efb0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2efc0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2efd0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2efe0 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2eff0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f000 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
2f010 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2f020 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
2f030 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
2f040 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
2f050 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
2f060 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2f070 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f080 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
2f090 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2f0a0 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
2f0b0 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
2f0c0 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
2f0d0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2f0e0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2f0f0 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
2f100 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2f110 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
2f120 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f130 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
2f140 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
2f150 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
2f160 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
2f170 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2f180 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2f190 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2f1a0 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2f1b0 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
2f1c0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2f1d0 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2f1e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2f1f0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2f200 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2f210 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2f220 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
2f230 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2f240 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2f250 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
2f260 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
2f270 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2f280 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2f290 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
2f2a0 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
2f2b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2f2c0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
2f2d0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2f2e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2f2f0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
2f300 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
2f310 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
2f320 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2f330 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2f340 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
2f350 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2f360 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2f370 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2f380 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2f390 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2f3a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2f3b0 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
2f3c0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2f3d0 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2f3e0 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
2f3f0 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
2f400 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
2f410 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
2f420 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
2f430 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
2f440 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
2f450 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
2f460 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
2f470 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
2f480 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
2f490 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
2f4a0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
2f4b0 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
2f4c0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
2f4d0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
2f4e0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
2f4f0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
2f500 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
2f510 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
2f520 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
2f530 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
2f540 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
2f550 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2f560 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2f570 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
2f580 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2f590 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
2f5a0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2f5b0 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
2f5c0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2f5d0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2f5e0 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
2f5f0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
2f600 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2f610 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2f620 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
2f630 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2f640 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2f650 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2f660 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2f670 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
2f680 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
2f690 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
2f6a0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2f6b0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2f6c0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
2f6d0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2f6e0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2f6f0 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
2f700 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
2f710 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2f720 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2f730 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
2f740 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
2f750 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2f760 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2f770 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2f780 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
2f790 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2f7a0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2f7b0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f  d> [CAST] to BLO
2f7c0 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  B.** <tr><td>  T
2f7d0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
2f7e0 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
2f7f0 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
2f800 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2f810 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2f820 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2f830 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
2f840 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
2f850 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
2f860 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
2f870 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2f880 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2f890 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
2f8a0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
2f8b0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
2f8c0 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
2f8d0 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
2f8e0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2f8f0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2f900 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
2f910 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
2f920 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
2f930 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
2f940 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  )^.**.** The tab
2f950 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72  le above makes r
2f960 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e  eference to stan
2f970 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66  dard C library f
2f980 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a  unctions atoi().
2f990 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20  ** and atof().  
2f9a0 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
2f9b0 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65  really use these
2f9c0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20   functions.  It 
2f9d0 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65  has its.** own e
2f9e0 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e  quivalent intern
2f9f0 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68  al routines.  Th
2fa00 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f  e atoi() and ato
2fa10 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  f() names are.**
2fa20 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62   used in the tab
2fa30 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61  le for brevity a
2fa40 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20  nd because they 
2fa50 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20  are familiar to 
2fa60 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61  most.** C progra
2fa70 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  mmers..**.** Not
2fa80 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
2fa90 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
2faa0 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
2fab0 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
2fac0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
2fad0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2fae0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
2faf0 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
2fb00 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2fb10 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
2fb20 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
2fb30 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
2fb40 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
2fb50 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
2fb60 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
2fb70 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
2fb80 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2fb90 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2fba0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
2fbb0 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
2fbc0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
2fbd0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2fbe0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2fbf0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
2fc00 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
2fc10 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
2fc20 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
2fc30 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
2fc40 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
2fc50 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2fc60 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
2fc70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fc80 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
2fc90 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2fca0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
2fcb0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2fcc0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2fcd0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2fce0 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
2fcf0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2fd00 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2fd10 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
2fd20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2fd30 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
2fd40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2fd50 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
2fd60 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2fd70 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2fd80 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
2fd90 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
2fda0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
2fdb0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
2fdc0 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
2fdd0 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
2fde0 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
2fdf0 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
2fe00 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
2fe10 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
2fe20 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
2fe30 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
2fe40 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
2fe50 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
2fe60 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
2fe70 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
2fe80 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
2fe90 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
2fea0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
2feb0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
2fec0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
2fed0 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
2fee0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
2fef0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
2ff00 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
2ff10 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
2ff20 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
2ff30 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
2ff40 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
2ff50 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
2ff60 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
2ff70 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
2ff80 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
2ff90 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
2ffa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2ffb0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2ffc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ffd0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2ffe0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2fff0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
30000 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
30010 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
30020 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
30030 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
30040 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
30050 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30060 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
30070 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
30080 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
30090 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
300a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
300b0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
300c0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
300d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
300e0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
300f0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
30100 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
30110 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
30120 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
30130 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
30140 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
30150 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
30160 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
30170 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
30180 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
30190 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
301a0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
301b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
301c0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
301d0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
301e0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
301f0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
30200 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
30210 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
30220 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
30230 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30240 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
30250 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
30260 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
30270 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
30280 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
30290 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
302a0 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
302b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
302c0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
302d0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
302e0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
302f0 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
30300 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
30310 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
30320 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
30330 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
30340 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f  cally.  Do <b>no
30350 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70  t</b> pass the p
30360 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
30370 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
30380 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
30390 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
303a0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
303b0 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
303c0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
303d0 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
303e0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
303f0 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
30400 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
30410 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
30420 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
30430 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
30440 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
30450 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
30460 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
30470 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
30480 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
30490 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
304a0 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
304b0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
304c0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
304d0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
304e0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
304f0 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
30500 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
30510 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
30520 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
30530 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
30540 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
30550 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
30560 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30570 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
30580 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
30590 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
305a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
305b0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
305c0 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69  _API double sqli
305d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
305e0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
305f0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
30600 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
30610 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
30620 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30630 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
30640 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
30650 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30660 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
30670 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
30680 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
30690 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
306a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
306b0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
306c0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
306d0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
306e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
306f0 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
30700 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
30710 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
30720 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
30730 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
30740 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
30750 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
30760 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
30770 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
30780 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30790 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
307a0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
307b0 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
307c0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
307d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
307e0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
307f0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
30800 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
30810 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30820 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
30830 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
30840 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
30850 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
30860 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
30870 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
30880 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
30890 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
308a0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
308b0 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
308c0 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
308d0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
308e0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
308f0 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
30900 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
30910 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
30920 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
30930 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
30940 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
30950 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
30960 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30970 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
30980 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
30990 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
309a0 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
309b0 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
309c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
309d0 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
309e0 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
309f0 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
30a00 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
30a10 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
30a20 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
30a30 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
30a40 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
30a50 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
30a60 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
30a70 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
30a80 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
30a90 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
30aa0 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
30ab0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
30ac0 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
30ad0 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
30ae0 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
30af0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
30b00 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
30b10 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
30b20 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
30b30 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
30b40 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
30b50 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
30b60 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
30b70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
30b80 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
30b90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
30ba0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
30bb0 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
30bc0 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
30bd0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
30be0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
30bf0 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
30c00 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
30c10 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
30c20 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
30c30 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
30c40 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
30c50 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ption..*/.SQLITE
30c60 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
30c70 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
30c80 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
30c90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30ca0 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
30cb0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
30cc0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
30cd0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
30ce0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
30cf0 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
30d00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
30d10 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
30d20 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
30d30 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
30d40 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
30d50 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
30d60 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
30d70 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
30d80 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
30d90 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
30da0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
30db0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
30dc0 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
30dd0 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
30de0 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
30df0 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
30e00 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
30e10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
30e20 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
30e30 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
30e40 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
30e50 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
30e60 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
30e70 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
30e80 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
30e90 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
30ea0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
30eb0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
30ec0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
30ed0 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
30ee0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
30ef0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
30f00 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
30f10 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
30f20 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
30f30 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
30f40 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
30f50 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
30f60 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
30f70 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
30f80 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
30f90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
30fa0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
30fb0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30fc0 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
30fd0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
30fe0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
30ff0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
31000 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
31010 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
31020 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
31030 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
31040 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
31050 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
31060 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
31070 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
31080 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
31090 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
310a0 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50   S..*/.SQLITE_AP
310b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  I int sqlite3_re
310c0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
310d0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
310e0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
310f0 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
31100 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
31110 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
31120 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
31130 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
31140 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
31150 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
31160 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
31170 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
31180 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
31190 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
311a0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
311b0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
311c0 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
311d0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
311e0 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
311f0 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
31200 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
31210 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
31220 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
31230 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
31240 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
31250 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
31260 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
31270 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
31280 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
31290 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
312a0 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
312b0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
312c0 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
312d0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
312e0 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
312f0 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
31300 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
31310 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
31320 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
31330 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
31340 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
31350 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
31360 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
31370 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31380 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
31390 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
313a0 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
313b0 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
313c0 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
313d0 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
313e0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
313f0 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
31400 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
31410 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
31420 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
31430 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31440 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
31450 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
31460 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
31470 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
31480 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
31490 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
314a0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
314b0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
314c0 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
314d0 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
314e0 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
314f0 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
31500 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
31510 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
31520 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
31530 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
31540 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
31550 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
31560 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
31570 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
31580 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
31590 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
315a0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
315b0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
315c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
315d0 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
315e0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
315f0 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
31600 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
31610 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
31620 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
31630 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
31640 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
31650 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
31660 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
31670 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
31680 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
31690 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
316a0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
316b0 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
316c0 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
316d0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
316e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
316f0 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
31700 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
31710 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
31720 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
31730 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
31740 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
31750 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
31760 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
31770 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
31780 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
31790 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
317a0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
317b0 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
317c0 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
317d0 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
317e0 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c  eters.  The appl
317f0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73  ication should s
31800 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  et this paramete
31810 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r to.** [SQLITE_
31820 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20  UTF16LE] if the 
31830 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
31840 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  ntation invokes 
31850 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
31860 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f  ue_text16le()] o
31870 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b  n an input, or [
31880 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20  SQLITE_UTF16BE] 
31890 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  if the.** implem
318a0 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
318b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
318c0 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61  text16be()] on a
318d0 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b  n input, or.** [
318e0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66  SQLITE_UTF16] if
318f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
31900 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65  text16()] is use
31910 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  d, or [SQLITE_UT
31920 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  F8].** otherwise
31930 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c  .  ^The same SQL
31940 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
31950 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
31960 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67  iple times using
31970 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72  .** different pr
31980 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
31990 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66  odings, with dif
319a0 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  ferent implement
319b0 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61  ations for.** ea
319c0 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20  ch encoding..** 
319d0 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
319e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
319f0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
31a00 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
31a10 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
31a20 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
31a30 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
31a40 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
31a50 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
31a60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
31a70 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61  rth parameter ma
31a80 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20  y optionally be 
31a90 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  ORed with [SQLIT
31aa0 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d  E_DETERMINISTIC]
31ab0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68  .** to signal th
31ac0 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  at the function 
31ad0 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
31ae0 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75  rn the same resu
31af0 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20  lt given.** the 
31b00 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68  same inputs with
31b10 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  in a single SQL 
31b20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74  statement.  Most
31b30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
31b40 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73  re.** determinis
31b50 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d  tic.  The built-
31b60 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51  in [random()] SQ
31b70 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e  L function is an
31b80 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a   example of a.**
31b90 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69   function that i
31ba0 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73  s not determinis
31bb0 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65  tic.  The SQLite
31bc0 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69   query planner i
31bd0 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72  s able to.** per
31be0 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20  form additional 
31bf0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e  optimizations on
31c00 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66   deterministic f
31c10 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65  unctions, so use
31c20 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
31c30 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
31c40 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d  ] flag is recomm
31c50 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73  ended where poss
31c60 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ible..**.** ^(Th
31c70 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
31c80 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
31c90 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
31ca0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
31cb0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
31cc0 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
31cd0 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
31ce0 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
31cf0 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
31d00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
31d10 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65  h, seventh and e
31d20 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73  ighth parameters
31d30 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
31d40 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
31d50 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
31d60 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
31d70 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
31d80 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
31d90 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
31da0 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
31db0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
31dc0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
31dd0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
31de0 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
31df0 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
31e00 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  rs must be passe
31e10 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
31e20 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
31e30 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
31e40 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
31e50 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
31e60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
31e70 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
31e80 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70  Final and NULL p
31e90 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70  ointer must be p
31ea0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
31eb0 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
31ec0 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
31ed0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
31ee0 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
31ef0 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c  pointers for all
31f00 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
31f10 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
31f20 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e  .** ^(If the nin
31f30 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
31f40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31f50 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
31f60 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
31f70 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
31f80 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
31f90 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
31fa0 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
31fb0 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
31fc0 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
31fd0 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
31fe0 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
31ff0 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
32000 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
32010 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
32020 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
32030 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
32040 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
32050 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
32060 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32070 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
32080 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
32090 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
320a0 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
320b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
320c0 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
320d0 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
320e0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
320f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
32100 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
32110 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
32120 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
32130 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
32140 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32150 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
32160 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
32170 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
32180 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
32190 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
321a0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
321b0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
321c0 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
321d0 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
321e0 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
321f0 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
32200 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
32210 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
32220 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
32230 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
32240 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
32250 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
32260 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
32270 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
32280 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
32290 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
322a0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
322b0 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
322c0 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
322d0 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
322e0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
322f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
32300 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
32310 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63  e nArg.  ^A func
32320 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
32330 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
32340 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
32350 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
32360 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
32370 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
32380 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
32390 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
323a0 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
323b0 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  ** ^A function w
323c0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
323d0 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
323e0 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
323f0 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
32400 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
32410 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
32420 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
32430 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
32440 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
32450 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
32460 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e  ** ^Built-in fun
32470 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
32480 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
32490 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
324a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
324b0 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
324c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
324d0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
324e0 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
324f0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
32500 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
32510 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
32520 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
32530 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
32540 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
32550 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
32560 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
32570 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
32580 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
32590 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
325a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
325b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
325c0 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
325d0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
325e0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
325f0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
32600 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
32610 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
32620 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
32630 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
32640 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
32650 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
32660 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32670 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
32680 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
32690 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
326a0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c  context*).);.SQL
326b0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
326c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
326d0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
326e0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f   *db,.  const vo
326f0 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  id *zFunctionNam
32700 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
32710 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
32720 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
32730 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
32740 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
32750 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
32760 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
32770 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
32780 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
32790 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
327a0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
327b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
327c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
327d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
327e0 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
327f0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
32800 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
32810 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
32820 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
32830 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
32840 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
32850 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32860 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
32870 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
32880 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
32890 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
328a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
328b0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
328c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
328d0 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
328e0 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
328f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32900 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
32910 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
32920 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
32930 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
32940 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
32950 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
32960 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
32970 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
32980 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
32990 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20  F8           1  
329a0 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31    /* IMP: R-3751
329b0 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69  4-35566 */.#defi
329c0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
329d0 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a  E        2    /*
329e0 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37   IMP: R-03371-37
329f0 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  637 */.#define S
32a00 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
32a10 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50       3    /* IMP
32a20 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20  : R-51971-34154 
32a30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
32a40 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
32a50 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
32a60 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
32a70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
32a80 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
32a90 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74  5    /* Deprecat
32aa0 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
32ab0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
32ac0 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
32ad0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32ae0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
32af0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
32b00 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a  nction Flags.**.
32b10 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
32b20 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74  ts may be ORed t
32b30 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65  ogether with the
32b40 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
32b50 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65  8 | preferred te
32b60 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20  xt encoding] as 
32b70 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
32b80 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ent.** to [sqlit
32b90 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
32ba0 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
32bb0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
32bc0 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
32bd0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32be0 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23  tion_v2()]..*/.#
32bf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
32c00 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30  TERMINISTIC    0
32c10 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x800../*.** CAPI
32c20 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
32c30 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
32c40 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
32c50 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
32c60 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
32c70 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
32c80 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
32c90 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
32ca0 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
32cb0 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
32cc0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
32cd0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
32ce0 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
32cf0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
32d00 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
32d10 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
32d20 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
32d30 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
32d40 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
32d50 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
32d60 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
32d70 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
32d80 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  u what they do..
32d90 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
32da0 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
32db0 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  D.SQLITE_API SQL
32dc0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
32dd0 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
32de0 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
32df0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
32e00 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
32e10 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
32e20 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
32e30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
32e40 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
32e50 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
32e60 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
32e70 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
32e80 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
32e90 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
32ea0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
32eb0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
32ec0 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
32ed0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
32ee0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
32ef0 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65  ATED void sqlite
32f00 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
32f10 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
32f20 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
32f30 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
32f40 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
32f50 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
32f60 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a  te3_int64,int),.
32f70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32f80 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69        void*,sqli
32f90 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
32fa0 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
32fb0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
32fc0 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
32fd0 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a  eter Values.**.*
32fe0 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
32ff0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33000 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
33010 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
33020 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
33030 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
33040 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
33050 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
33060 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
33070 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
33080 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
33090 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
330a0 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
330b0 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
330c0 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
330d0 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
330e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
330f0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
33100 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33110 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
33120 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
33130 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
33140 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
33150 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
33160 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
33170 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
33180 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
33190 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
331a0 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
331b0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
331c0 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
331d0 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
331e0 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
331f0 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
33200 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
33210 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
33220 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
33230 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
33240 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
33250 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
33260 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
33270 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
33280 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
33290 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
332a0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
332b0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
332c0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
332d0 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
332e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
332f0 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
33300 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
33310 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
33320 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
33330 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65  s work just like
33340 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
33350 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  ng [column acces
33360 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20  s functions].** 
33370 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 73  except that thes
33380 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
33390 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
333a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
333b0 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69  e] object.** poi
333c0 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
333d0 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
333e0 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
333f0 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
33400 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
33410 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
33420 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
33430 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
33440 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  TF-16 string.** 
33450 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
33460 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
33470 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e  host machine.  ^
33480 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
33490 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
334a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
334b0 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
334c0 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
334d0 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
334e0 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
334f0 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
33500 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
33510 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
33520 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
33530 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
33540 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
33550 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
33560 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
33570 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
33580 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
33590 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
335a0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
335b0 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
335c0 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
335d0 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
335e0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
335f0 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
33600 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
33610 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
33620 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
33630 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
33640 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
33650 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
33660 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
33670 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
33680 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
33690 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
336a0 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
336b0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
336c0 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
336d0 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
336e0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  d.)^.**.** Pleas
336f0 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
33700 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
33710 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
33720 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64  pointer returned
33730 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
33740 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
33750 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
33760 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
33770 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33780 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
33790 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
337a0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
337b0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
337c0 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
337d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
337e0 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
337f0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
33800 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
33810 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
33820 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
33830 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
33840 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
33850 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
33860 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
33870 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
33880 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
33890 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
338a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
338b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
338c0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
338d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
338e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
338f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
33900 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
33910 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
33920 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
33930 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
33940 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
33950 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  API double sqlit
33960 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
33970 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33980 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
33990 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
339a0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
339b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
339c0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
339d0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
339e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
339f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
33a00 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
33a10 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
33a20 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
33a30 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
33a40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
33a50 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
33a60 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33a70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
33a80 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
33a90 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
33aa0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33ab0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
33ac0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
33ad0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
33ae0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33af0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
33b00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
33b10 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
33b20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
33b30 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
33b40 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
33b50 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
33b60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
33b70 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
33b80 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
33b90 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74  .**.** Implement
33ba0 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ations of aggreg
33bb0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
33bc0 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
33bd0 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
33be0 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
33bf0 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
33c00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
33c10 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
33c20 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33c30 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
33c40 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
33c50 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
33c60 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
33c70 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
33c80 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
33c90 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
33ca0 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
33cb0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
33cc0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
33cd0 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
33ce0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
33cf0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
33d00 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
33d10 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
33d20 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
33d30 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
33d40 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
33d50 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
33d60 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
33d70 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
33d80 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
33d90 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
33da0 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
33db0 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
33dc0 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
33dd0 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
33de0 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
33df0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
33e00 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
33e10 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
33e20 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
33e30 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
33e40 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
33e50 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
33e60 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
33e70 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
33e80 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
33e90 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
33ea0 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
33eb0 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
33ec0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33ed0 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
33ee0 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
33ef0 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
33f00 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
33f10 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
33f20 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
33f30 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
33f40 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
33f50 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
33f60 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20   .** when first 
33f70 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c  called if N is l
33f80 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
33f90 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
33fa0 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  a memory.** allo
33fb0 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
33fc0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
33fd0 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
33fe0 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
33ff0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
34000 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
34010 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
34020 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
34030 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
34040 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
34050 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
34060 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
34070 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
34080 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
34090 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
340a0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
340b0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
340c0 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
340d0 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
340e0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
340f0 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46  ^  Within the xF
34100 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69  inal callback, i
34110 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74  t is customary t
34120 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20  o set.** N=0 in 
34130 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
34140 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
34150 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20  xt(C,N) so that 
34160 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73  no .** pointless
34170 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
34180 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a  ons occur..**.**
34190 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74   ^SQLite automat
341a0 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
341b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
341c0 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
341d0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
341e0 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67  xt() when the ag
341f0 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f  gregate query co
34200 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
34210 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
34220 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70  er must be a cop
34230 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
34240 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
34250 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
34260 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
34270 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
34280 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70  .** to the xStep
34290 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
342a0 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
342b0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
342c0 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
342d0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
342e0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
342f0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
34300 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
34310 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
34320 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
34330 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
34340 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
34350 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
34360 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
34370 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34380 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
34390 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
343a0 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
343b0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
343c0 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
343d0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
343e0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
343f0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
34400 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
34410 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
34420 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
34430 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
34440 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
34450 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
34460 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
34470 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
34480 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
34490 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
344a0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
344b0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
344c0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
344d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
344e0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
344f0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
34500 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
34510 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34520 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
34530 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
34540 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
34550 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
34560 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34570 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34580 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
34590 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
345a0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
345b0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
345c0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
345d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
345e0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
345f0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
34600 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34610 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
34620 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
34630 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
34640 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
34650 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
34660 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
34670 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
34680 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
34690 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
346a0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
346b0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
346c0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
346d0 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
346e0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
346f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
34700 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34710 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
34720 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
34730 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
34740 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28  may be used by (
34750 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53  non-aggregate) S
34760 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
34770 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
34780 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  adata with argum
34790 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
347a0 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
347b0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
347c0 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
347d0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
347e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
347f0 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
34800 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
34810 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
34820 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
34830 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70  etadata may be p
34840 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78  reserved.  An ex
34850 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72  ample.** of wher
34860 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20  e this might be 
34870 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72  useful is in a r
34880 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
34890 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75  n matching.** fu
348a0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
348b0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
348c0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
348d0 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74  ession can be st
348e0 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64  ored as.** metad
348f0 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
34900 69 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20  ith the pattern 
34910 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65  string.  .** The
34920 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  n as long as the
34930 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20   pattern string 
34940 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65  remains the same
34950 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65  ,.** the compile
34960 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
34970 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
34980 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
34990 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
349a0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
349b0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
349c0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
349d0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
349e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
349f0 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
34a00 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
34a10 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
34a20 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
34a30 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
34a40 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
34a50 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
34a60 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34a70 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65  unction. ^If the
34a80 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74  re is no metadat
34a90 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
34aa0 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f  with the functio
34ab0 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73  n argument, this
34ac0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
34ad0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
34ae0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55  .** returns a NU
34af0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
34b00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
34b10 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
34b20 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  ,X) interface sa
34b30 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74  ves P as metadat
34b40 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
34b50 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
34b60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
34b70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
34b80 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20   ^Subsequent.** 
34b90 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
34ba0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _get_auxdata(C,N
34bb0 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20  ) return P from 
34bc0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
34bd0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
34be0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
34bf0 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61  call if the meta
34c00 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61  data is still va
34c10 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69  lid or.** NULL i
34c20 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 68  f the metadata h
34c30 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 65  as been discarde
34c40 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63  d..** ^After eac
34c50 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
34c60 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
34c70 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 69  N,P,X) where X i
34c80 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53  s not NULL,.** S
34c90 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
34ca0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
34cb0 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68   function X with
34cc0 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 61   parameter P exa
34cd0 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68  ctly.** once, wh
34ce0 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  en the metadata 
34cf0 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  is discarded..**
34d00 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
34d10 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 6d  to discard the m
34d20 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 74  etadata at any t
34d30 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20  ime, including: 
34d40 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  <ul>.** <li> whe
34d50 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
34d60 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
34d70 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20  ameter changes, 
34d80 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  or.** <li> when 
34d90 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
34da0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
34db0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
34dc0 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  led for the.**  
34dd0 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e      SQL statemen
34de0 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68  t, or.** <li> wh
34df0 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  en sqlite3_set_a
34e00 75 78 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f  uxdata() is invo
34e10 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65  ked again on the
34e20 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c   same parameter,
34e30 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69   or.** <li> duri
34e40 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ng the original 
34e50 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34e60 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20  ata() call when 
34e70 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20  a memory .**    
34e80 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72    allocation err
34e90 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e  or occurs. </ul>
34ea0 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  )^.**.** Note th
34eb0 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e  e last bullet in
34ec0 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68   particular.  Th
34ed0 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 20 69  e destructor X i
34ee0 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  n .** sqlite3_se
34ef0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
34f00 58 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  X) might be call
34f10 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ed immediately, 
34f20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71  before the.** sq
34f30 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
34f40 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 76  a() interface ev
34f50 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e  en returns.  Hen
34f60 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ce sqlite3_set_a
34f70 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75  uxdata().** shou
34f80 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61  ld be called nea
34f90 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  r the end of the
34fa0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
34fb0 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65  entation and the
34fc0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  .** function imp
34fd0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
34fe0 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20  ld not make any 
34ff0 75 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a  use of P after.*
35000 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
35010 78 64 61 74 61 28 29 20 68 61 73 20 62 65 65 6e  xdata() has been
35020 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   called..**.** ^
35030 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
35040 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
35050 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
35060 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
35070 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
35080 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 63  eters that are c
35090 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73  ompile-time cons
350a0 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67  tants, including
350b0 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
350c0 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65  es and [paramete
350d0 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69  rs] and expressi
350e0 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f  ons composed fro
350f0 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a  m the same.)^.**
35100 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
35110 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
35120 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
35130 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
35140 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
35150 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
35160 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
35170 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
35180 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
35190 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
351a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
351b0 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
351c0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
351d0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
351e0 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
351f0 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
35200 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
35210 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
35220 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
35230 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
35240 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
35250 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
35260 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
35270 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
35280 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
35290 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
352a0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
352b0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
352c0 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63   ^If the destruc
352d0 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
352e0 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
352f0 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
35300 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
35310 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
35320 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
35330 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
35340 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
35350 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54  e destroyed.  ^T
35360 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
35370 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
35380 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
35390 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
353a0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
353b0 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
353c0 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
353d0 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
353e0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
353f0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
35400 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
35410 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
35420 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
35430 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
35440 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
35450 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
35460 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  lers..*/.typedef
35470 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
35480 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
35490 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
354a0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
354b0 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
354c0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
354d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
354e0 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
354f0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
35500 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
35510 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
35520 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
35530 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
35540 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
35550 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
35560 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
35570 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
35580 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
35590 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
355a0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
355b0 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
355c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
355d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
355e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
355f0 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
35600 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
35610 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
35620 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
35630 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
35640 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69  he [parameter bi
35650 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66  nding] family of
35660 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  .** functions us
35670 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ed to bind value
35680 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
35690 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
356a0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
356b0 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51  Refer to the [SQ
356c0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63  L parameter] doc
356d0 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
356e0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
356f0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
35700 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35710 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
35720 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
35730 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
35740 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35750 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
35760 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
35770 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
35780 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
35790 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
357a0 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
357b0 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
357c0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
357d0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
357e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
357f0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
35800 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
35810 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
35820 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
35830 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35840 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
35850 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
35860 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
35870 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
35880 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
35890 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
358a0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
358b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
358c0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
358d0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
358e0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
358f0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
35900 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35910 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
35920 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
35930 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
35940 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
35950 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35960 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35970 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
35980 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
35990 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
359a0 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
359b0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
359c0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
359d0 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ption..** ^SQLit
359e0 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
359f0 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
35a00 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
35a10 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
35a20 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
35a30 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
35a40 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
35a50 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
35a60 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
35a70 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65  ^SQLite interpre
35a80 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
35a90 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
35aa0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
35ab0 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
35ac0 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  F-8. ^SQLite.** 
35ad0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
35ae0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
35af0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
35b00 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
35b10 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
35b20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20  order.  ^If the 
35b30 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
35b40 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
35b50 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
35b60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35b70 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
35b80 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
35b90 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
35ba0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
35bb0 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
35bc0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
35bd0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
35be0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
35bf0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
35c00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
35c10 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
35c20 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
35c30 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
35c40 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
35c50 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
35c60 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
35c70 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
35c80 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
35c90 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
35ca0 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ge..** ^The sqli
35cb0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35cc0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
35cd0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
35ce0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
35cf0 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20   a private copy 
35d00 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
35d10 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
35d20 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
35d30 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
35d40 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
35d50 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
35d60 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
35d70 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
35d80 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
35d90 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  m..** ^The sqlit
35da0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
35db0 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
35dc0 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
35dd0 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
35de0 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
35df0 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
35e00 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
35e10 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74  on.  ^By default
35e20 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
35e30 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
35e40 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75  ROR.  ^A subsequ
35e50 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
35e60 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35e70 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
35e80 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
35e90 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72  ) resets the err
35ea0 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54  or code to SQLIT
35eb0 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e  E_ERROR..**.** ^
35ec0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35ed0 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
35ee0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
35ef0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
35f00 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69  ow an.** error i
35f10 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
35f20 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
35f30 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
35f40 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
35f50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
35f60 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
35f70 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
35f80 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
35f90 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69  ow an.** error i
35fa0 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
35fb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
35fc0 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
35fd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35fe0 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72  sult_int() inter
35ff0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
36000 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
36010 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36020 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36030 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62  n to be the 32-b
36040 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
36050 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
36060 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
36070 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ment..** ^The sq
36080 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
36090 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
360a0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
360b0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
360c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
360d0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
360e0 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
360f0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
36100 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
36110 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
36120 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36130 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
36140 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
36150 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
36160 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
36170 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36180 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55  unction to be NU
36190 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
361a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
361b0 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  xt(), sqlite3_re
361c0 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a  sult_text16(),.*
361d0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
361e0 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64  _text16le(), and
361f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36200 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72  text16be() inter
36210 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65  faces.** set the
36220 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
36230 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36240 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36250 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78  n to be.** a tex
36260 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  t string which i
36270 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  s represented as
36280 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e   UTF-8, UTF-16 n
36290 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
362a0 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
362b0 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le endian, or UT
362c0 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c  F-16 big endian,
362d0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
362e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
362f0 65 73 75 6c 74 5f 74 65 78 74 36 34 28 29 20 69  esult_text64() i
36300 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
36310 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
36320 66 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74  f an.** applicat
36330 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
36340 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 74 65 78  tion to be a tex
36350 74 20 73 74 72 69 6e 67 20 69 6e 20 61 6e 20 65  t string in an e
36360 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73 70 65 63 69  ncoding.** speci
36370 66 69 65 64 20 62 79 20 74 68 65 20 66 69 66 74  fied by the fift
36380 68 20 28 61 6e 64 20 6c 61 73 74 29 20 70 61 72  h (and last) par
36390 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 6d 75  ameter, which mu
363a0 73 74 20 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20  st be one.** of 
363b0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
363c0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b  SQLITE_UTF16], [
363d0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
363e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
363f0 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  6LE]..** ^SQLite
36400 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
36410 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
36420 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
36430 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
36440 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
36450 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36460 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
36470 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
36480 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
36490 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
364a0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
364b0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
364c0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
364d0 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
364e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
364f0 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
36500 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
36510 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
36520 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
36530 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
36540 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
36550 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
36560 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
36570 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
36580 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
36590 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
365a0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
365b0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
365c0 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
365d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
365e0 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
365f0 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20  result.  If the 
36600 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
36610 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
36620 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62  hen it.** must b
36630 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
36640 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e  t into the strin
36650 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  g where the NUL 
36660 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
36670 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68  .** appear if th
36680 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e  e string where N
36690 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  UL terminated.  
366a0 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
366b0 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69  cters occur.** i
366c0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20  n the string at 
366d0 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68  a byte offset th
366e0 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  at is less than 
366f0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
36700 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65   3rd.** paramete
36710 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  r, then the resu
36720 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c  lting string wil
36730 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  l contain embedd
36740 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a  ed NULs and the.
36750 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  ** result of exp
36760 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69  ressions operati
36770 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69  ng on strings wi
36780 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
36790 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
367a0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
367b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
367c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
367d0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
367e0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
367f0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
36800 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
36810 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
36820 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
36830 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
36840 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
36850 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
36860 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
36870 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
36880 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
36890 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
368a0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
368b0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
368c0 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
368d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
368e0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
368f0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
36900 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
36910 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
36920 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
36930 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
36940 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
36950 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
36960 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
36970 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
36980 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
36990 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
369a0 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
369b0 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
369c0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
369d0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
369e0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
369f0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
36a00 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
36a10 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
36a20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
36a30 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
36a40 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
36a50 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
36a60 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
36a70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
36a80 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
36a90 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
36aa0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
36ab0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
36ac0 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
36ad0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36ae0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
36af0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
36b00 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
36b10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
36b20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
36b30 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
36b40 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
36b50 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
36b60 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
36b70 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
36b80 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
36b90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36ba0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
36bb0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
36bc0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
36bd0 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
36be0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
36bf0 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
36c00 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
36c10 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
36c20 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
36c30 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
36c40 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
36c50 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
36c60 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
36c70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
36c80 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
36c90 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
36ca0 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
36cb0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
36cc0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
36cd0 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
36ce0 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
36cf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
36d00 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
36d10 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
36d20 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
36d30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
36d40 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
36d50 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
36d60 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
36d70 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
36d80 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
36d90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36da0 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
36db0 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
36dc0 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
36dd0 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
36de0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
36df0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
36e00 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36e10 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
36e20 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
36e30 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
36e40 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
36e50 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
36e60 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
36e70 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
36e80 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  xt*,const void*,
36e90 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
36ea0 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
36eb0 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f 69 64 28  te3_uint64,void(
36ec0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
36ed0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
36ee0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
36ef0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
36f00 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c  t*, double);.SQL
36f10 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
36f20 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36f30 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
36f40 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
36f50 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
36f60 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
36f70 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71  esult_error16(sq
36f80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36f90 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
36fa0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
36fb0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36fc0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
36fd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
36fe0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
36ff0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37000 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
37010 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
37020 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37030 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37040 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
37050 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
37060 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
37070 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37080 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
37090 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  text*, int);.SQL
370a0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
370b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
370c0 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  4(sqlite3_contex
370d0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t*, sqlite3_int6
370e0 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  4);.SQLITE_API v
370f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37100 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
37110 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
37120 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
37130 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
37140 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37150 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
37160 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
37170 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  ));.SQLITE_API v
37180 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37190 6c 74 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65  lt_text64(sqlite
371a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
371b0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
371c0 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
371d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
371e0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
371f0 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
37200 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49   encoding);.SQLI
37210 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
37220 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
37230 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
37240 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
37250 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
37260 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
37270 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
37280 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
37290 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
372a0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
372b0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
372c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
372d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
372e0 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
372f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
37300 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
37310 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
37320 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
37330 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
37340 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
37350 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
37360 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
37370 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
37380 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
37390 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
373a0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
373b0 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
373c0 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
373d0 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e  equences.**.** ^
373e0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
373f0 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20  add, remove, or 
37400 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74  modify a [collat
37410 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a  ion] associated.
37420 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
37430 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37440 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
37450 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
37460 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  t..**.** ^The na
37470 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  me of the collat
37480 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73  ion is a UTF-8 s
37490 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
374a0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
374b0 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
374c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
374d0 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
374e0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
374f0 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
37500 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
37510 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37520 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c  on16()..** ^Coll
37530 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74  ation names that
37540 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61   compare equal a
37550 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c  ccording to [sql
37560 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d  ite3_strnicmp()]
37570 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
37580 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d  ed to be the sam
37590 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e name..**.** ^(
375a0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
375b0 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75  nt (eTextRep) mu
375c0 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  st be one of the
375d0 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c   constants:.** <
375e0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
375f0 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c  ITE_UTF8],.** <l
37600 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
37610 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  LE],.** <li> [SQ
37620 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
37630 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
37640 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  TF16], or.** <li
37650 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  > [SQLITE_UTF16_
37660 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75  ALIGNED]..** </u
37670 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65  l>)^.** ^The eTe
37680 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64  xtRep argument d
37690 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e  etermines the en
376a0 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67  coding of string
376b0 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74  s passed.** to t
376c0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
376d0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20  ction callback, 
376e0 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54  xCallback..** ^T
376f0 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
37700 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54  ] and [SQLITE_UT
37710 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
37720 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70  ues for eTextRep
37730 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67  .** force string
37740 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69  s to be UTF16 wi
37750 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  th native byte o
37760 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  rder..** ^The [S
37770 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
37780 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65  NED] value for e
37790 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73  TextRep forces s
377a0 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a  trings to begin.
377b0 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79  ** on an even by
377c0 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a  te address..**.*
377d0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72  * ^The fourth ar
377e0 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73  gument, pArg, is
377f0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
37800 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61  data pointer tha
37810 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  t is passed.** t
37820 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
37830 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
37840 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
37850 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e  nction callback.
37860 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
37870 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c  h argument, xCal
37880 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e  lback, is a poin
37890 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ter to the colla
378a0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ting function..*
378b0 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c  * ^Multiple coll
378c0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
378d0 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
378e0 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  d using the same
378f0 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74   name but.** wit
37900 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  h different eTex
37910 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20  tRep parameters 
37920 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  and SQLite will 
37930 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a  use whichever.**
37940 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
37950 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
37960 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e  unt of data tran
37970 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  sformation..** ^
37980 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b  If the xCallback
37990 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c   argument is NUL
379a0 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  L then the colla
379b0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
379c0 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57  .** deleted.  ^W
379d0 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e  hen all collatin
379e0 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69  g functions havi
379f0 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
37a00 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a   are deleted,.**
37a10 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20   that collation 
37a20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61  is no longer usa
37a30 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
37a40 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37a50 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  on callback is i
37a60 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f  nvoked with a co
37a70 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a  py of the pArg .
37a80 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  ** application d
37a90 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ata pointer and 
37aa0 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73  with two strings
37ab0 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
37ac0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
37ad0 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72   the eTextRep ar
37ae0 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c  gument.  The col
37af0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
37b00 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a  must return an.*
37b10 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69  * integer that i
37b20 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  s negative, zero
37b30 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a  , or positive.**
37b40 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74   if the first st
37b50 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61  ring is less tha
37b60 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  n, equal to, or 
37b70 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
37b80 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70   second,.** resp
37b90 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c  ectively.  A col
37ba0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
37bb0 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75  must always retu
37bc0 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77  rn the same answ
37bd0 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20  er.** given the 
37be0 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66  same inputs.  If
37bf0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c   two or more col
37c00 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
37c10 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a   are registered.
37c20 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63  ** to the same c
37c30 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75  ollation name (u
37c40 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65  sing different e
37c50 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20  TextRep values) 
37c60 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74  then all.** must
37c70 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c   give an equival
37c80 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20  ent answer when 
37c90 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75  invoked with equ
37ca0 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e  ivalent strings.
37cb0 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  .** The collatin
37cc0 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
37cd0 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69  obey the followi
37ce0 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f  ng properties fo
37cf0 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73  r all.** strings
37d00 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a   A, B, and C:.**
37d10 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
37d20 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d   If A==B then B=
37d30 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =A..** <li> If A
37d40 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65  ==B and B==C the
37d50 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20  n A==C..** <li> 
37d60 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42  If A&lt;B THEN B
37d70 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49  &gt;A..** <li> I
37d80 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c  f A&lt;B and B&l
37d90 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e  t;C then A&lt;C.
37da0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
37db0 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66  If a collating f
37dc0 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e  unction fails an
37dd0 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63  y of the above c
37de0 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
37df0 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67  hat.** collating
37e00 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65   function is  re
37e10 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65  gistered and use
37e20 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
37e30 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
37e40 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
37e50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37e60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37e70 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
37e80 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
37e90 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
37ea0 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74  * with the addit
37eb0 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65  ion that the xDe
37ec0 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
37ed0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72  s invoked on pAr
37ee0 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  g when.** the co
37ef0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37f00 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   is deleted..** 
37f10 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74  ^Collating funct
37f20 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64  ions are deleted
37f30 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f   when they are o
37f40 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74  verridden by lat
37f50 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74  er.** calls to t
37f60 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
37f70 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  ation functions 
37f80 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  or when the.** [
37f90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37fa0 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75  ion] is closed u
37fb0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
37fc0 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ose()]..**.** ^T
37fd0 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
37fe0 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f  back is <u>not</
37ff0 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65  u> called if the
38000 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65   .** sqlite3_cre
38010 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
38020 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  () function fail
38030 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  s.  Applications
38040 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20   that invoke.** 
38050 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
38060 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69  ollation_v2() wi
38070 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44  th a non-NULL xD
38080 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20  estroy argument 
38090 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b  should .** check
380a0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
380b0 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20   and dispose of 
380c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
380d0 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  data pointer.** 
380e0 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65  themselves rathe
380f0 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67  r than expecting
38100 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20   SQLite to deal 
38110 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d  with it for them
38120 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66  ..** This is dif
38130 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72  ferent from ever
38140 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
38150 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69  nterface.  The i
38160 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a  nconsistency .**
38170 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20   is unfortunate 
38180 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  but cannot be ch
38190 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72  anged without br
381a0 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73  eaking backwards
381b0 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69   .** compatibili
381c0 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ty..**.** See al
381d0 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f  so:  [sqlite3_co
381e0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
381f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
38200 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
38210 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  6()]..*/.SQLITE_
38220 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
38230 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
38240 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
38250 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
38260 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
38270 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
38280 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
38290 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
382a0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
382b0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53  onst void*).);.S
382c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
382d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
382e0 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
382f0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
38300 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
38310 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
38320 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
38330 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
38340 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
38350 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
38360 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
38370 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
38380 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
38390 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
383a0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
383b0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
383c0 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
383d0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
383e0 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
383f0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
38400 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
38410 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
38420 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
38430 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
38440 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
38450 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
38460 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
38470 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
38480 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
38490 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
384a0 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
384b0 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
384c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
384d0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
384e0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
384f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38500 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
38510 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
38520 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
38530 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
38540 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
38550 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
38560 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
38570 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
38580 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
38590 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
385a0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
385b0 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
385c0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
385d0 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
385e0 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
385f0 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
38600 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
38610 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
38620 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
38630 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
38640 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
38650 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
38660 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
38670 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
38680 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
38690 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
386a0 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
386b0 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
386c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
386d0 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
386e0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
386f0 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
38700 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
38710 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
38720 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
38730 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
38740 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
38750 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
38760 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
38770 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
38780 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74