/ Hex Artifact Content
Login

Artifact b815e35cd1a62e1f75302b423bea00c11c900d1b:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  y are supported 
07d0: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
07e0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
07f0: 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
0800: 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64  n writers should
0810: 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a   be aware that.*
0820: 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  * experimental i
0830: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
0840: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
0850: 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65  in point release
0860: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d  s..**.** These m
0870: 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65  acros used to re
0880: 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73  solve to various
0890: 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c   kinds of compil
08a0: 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a  er magic that.**
08b0: 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20   would generate 
08c0: 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73  warning messages
08d0: 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65 20   when they were 
08e0: 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a  used.  But that.
08f0: 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  ** compiler magi
0900: 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72  c ended up gener
0910: 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75  ating such a flu
0920: 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72  rry of bug repor
0930: 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61  ts.** that we ha
0940: 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20  ve taken it all 
0950: 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63  out and gone bac
0960: 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c  k to using simpl
0970: 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73  e.** noop macros
0980: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
0990: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23  ITE_DEPRECATED.#
09a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
09b0: 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a  PERIMENTAL../*.*
09c0: 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20 73  * Ensure these s
09d0: 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20  ymbols were not 
09e0: 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20  defined by some 
09f0: 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 20  previous header 
0a00: 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  file..*/.#ifdef 
0a10: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
0a20: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0a30: 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66  RSION.#endif.#if
0a40: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0a50: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65  ON_NUMBER.# unde
0a60: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a70: 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a  _NUMBER.#endif..
0a80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
0a90: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62  Compile-Time Lib
0aa0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0ab0: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  bers.**.** ^(The
0ac0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ad0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0ae0: 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71   macro in the sq
0af0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a  lite3.h header.*
0b00: 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61  * evaluates to a
0b10: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
0b20: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69  that is the SQLi
0b30: 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68  te version in th
0b40: 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59  e.** format "X.Y
0b50: 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20 74  .Z" where X is t
0b60: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
0b70: 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20   number (always 
0b80: 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33  3 for.** SQLite3
0b90: 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d  ) and Y is the m
0ba0: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
0bb0: 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65  ber and Z is the
0bc0: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e   release number.
0bd0: 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  )^.** ^(The [SQL
0be0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bf0: 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ER] C preprocess
0c00: 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65  or macro resolve
0c10: 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  s to an integer.
0c20: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c 75  ** with the valu
0c30: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0c40: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0c50: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65   X, Y, and Z are
0c60: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d   the same.** num
0c70: 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51  bers used in [SQ
0c80: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e  LITE_VERSION].)^
0c90: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56  .** The SQLITE_V
0ca0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f  ERSION_NUMBER fo
0cb0: 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65  r any given rele
0cc0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ase of SQLite wi
0cd0: 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61  ll also.** be la
0ce0: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72 65  rger than the re
0cf0: 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  lease from which
0d00: 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e 20   it is derived. 
0d10: 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a   Either Y will.*
0d20: 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61  * be held consta
0d30: 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  nt and Z will be
0d40: 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20   incremented or 
0d50: 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69  else Y will be i
0d60: 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e  ncremented.** an
0d70: 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65  d Z will be rese
0d80: 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t to zero..**.**
0d90: 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33   Since version 3
0da0: 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f  .6.18, SQLite so
0db0: 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62 65  urce code has be
0dc0: 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  en stored in the
0dd0: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
0de0: 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73  p://www.fossil-s
0df0: 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20  cm.org/">Fossil 
0e00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0e10: 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74  nagement.** syst
0e20: 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51  em</a>.  ^The SQ
0e30: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d  LITE_SOURCE_ID m
0e40: 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74  acro evaluates t
0e50: 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68  o.** a string wh
0e60: 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20 61  ich identifies a
0e70: 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65 63   particular chec
0e80: 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a  k-in of SQLite.*
0e90: 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e  * within its con
0ea0: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
0eb0: 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e  ement system.  ^
0ec0: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  The SQLITE_SOURC
0ed0: 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63  E_ID.** string c
0ee0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 65  ontains the date
0ef0: 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65   and time of the
0f00: 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20   check-in (UTC) 
0f10: 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68  and an SHA1.** h
0f20: 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72  ash of the entir
0f30: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a  e source tree..*
0f40: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
0f50: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0f60: 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  on()],.** [sqlit
0f70: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
0f80: 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65  mber()], [sqlite
0f90: 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a  3_sourceid()],.*
0fa0: 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  * [sqlite_versio
0fb0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
0fc0: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
0fd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
0fe0: 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20  _VERSION        
0ff0: 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69  "--VERS--".#defi
1000: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
1010: 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49  N_NUMBER --VERSI
1020: 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66  ON-NUMBER--.#def
1030: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1040: 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55  E_ID      "--SOU
1050: 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a  RCE-ID--"../*.**
1060: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1070: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
1080: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
1090: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10a0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
10b0: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
10c0: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
10d0: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
10e0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
10f0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1100: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1110: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1120: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1130: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1140: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
1150: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
1160: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1170: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
1180: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
1190: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11a0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
11b0: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
11c0: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
11d0: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
11e0: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
11f0: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1200: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1210: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1220: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1230: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1240: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
1250: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
1260: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
1270: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
1280: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
1290: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12a0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
12b0: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
12c0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
12d0: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
12e0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
12f0: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1300: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1310: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1320: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1330: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1340: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
1350: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
1360: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
1370: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1380: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1390: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13a0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
13b0: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
13c0: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
13d0: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
13e0: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
13f0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1400: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1410: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1420: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1430: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1440: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
1450: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
1460: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
1470: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
1480: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1490: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14a0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
14b0: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
14c0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
14d0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
14e0: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
14f0: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1500: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1510: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1520: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1530: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1540: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
1550: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
1560: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
1570: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
1580: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
1590: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15a0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
15b0: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
15c0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
15d0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
15e0: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
15f0: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1600: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1610: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1620: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ()]..*/.SQLITE_E
1630: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72  XTERN const char
1640: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
1650: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  [];.const char *
1660: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1670: 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20  on(void);.const 
1680: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1690: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e  urceid(void);.in
16a0: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
16b0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
16c0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16d0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
16e0: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
16f0: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1700: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1710: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1720: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1730: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
1740: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
1750: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
1760: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
1770: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
1780: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
1790: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
17a0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
17b0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
17c0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
17d0: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
17e0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
17f0: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1800: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1810: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1820: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1830: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
1840: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
1850: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
1860: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
1870: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
1880: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
1890: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
18a0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
18b0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
18c0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
18d0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
18e0: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
18f0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1900: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1910: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1920: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1930: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1940: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1950: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
1960: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
1970: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
1980: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
1990: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
19a0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
19b0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
19c0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
19d0: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
19e0: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
19f0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1a00: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1a10: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1a20: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1a30: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1a40: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1a50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1a60: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1a70: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1a80: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1a90: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1aa0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1ab0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1ac0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1ad0: 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65  DIAGS.int sqlite
1ae0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1af0: 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20  used(const char 
1b00: 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73  *zOptName);.cons
1b10: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1b20: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b30: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66  t(int N);.#endif
1b40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b50: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1b60: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1b70: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a  Threadsafe.**.**
1b80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68   ^The sqlite3_th
1b90: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
1ba0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ion returns zero
1bb0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
1bc0: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  ** SQLite was co
1bd0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1be0: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65  xing code omitte
1bf0: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  d due to the.** 
1c00: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1c10: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  FE] compile-time
1c20: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65   option being se
1c30: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51  t to 0..**.** SQ
1c40: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70  Lite can be comp
1c50: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74  iled with or wit
1c60: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57  hout mutexes.  W
1c70: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  hen.** the [SQLI
1c80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43  TE_THREADSAFE] C
1c90: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1ca0: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d  cro is 1 or 2, m
1cb0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1cc0: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1cd0: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1ce0: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
1cf0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d00: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
1d10: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
1d20: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
1d30: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
1d40: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
1d50: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
1d60: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
1d70: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
1d80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
1d90: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
1da0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
1db0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1dc0: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1dd0: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1de0: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1df0: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
1e00: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
1e10: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
1e20: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
1e30: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
1e40: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
1e50: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65   ^The default be
1e60: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
1e70: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
1e80: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
1e90: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1ea0: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c   used by an appl
1eb0: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20  ication to make 
1ec0: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1ed0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
1ee0: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69  te that it is li
1ef0: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61  nking against wa
1f00: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
1f10: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73  ** the desired s
1f20: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53  etting of the [S
1f30: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f40: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54  ] macro..**.** T
1f50: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  his interface on
1f60: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68  ly reports on th
1f70: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
1f80: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20  utex setting.** 
1f90: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1fa0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e  HREADSAFE] flag.
1fb0: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
1fc0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
1fd0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fe0: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d  E=1 or =2 then m
1ff0: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
2000: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
2010: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
2020: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
2030: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
2040: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2050: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
2060: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
2070: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2080: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
2090: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
20a0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
20b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
20c0: 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65  IALIZED].  ^(The
20d0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
20e0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
20f0: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
2100: 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79  ction shows only
2110: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
2120: 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20  e setting of.** 
2130: 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e  thread safety, n
2140: 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20  ot any run-time 
2150: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20  changes to that 
2160: 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a  setting made by.
2170: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  ** sqlite3_confi
2180: 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  g(). In other wo
2190: 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20  rds, the return 
21a0: 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
21b0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a  e3_threadsafe().
21c0: 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20  ** is unchanged 
21d0: 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  by calls to sqli
21e0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a  te3_config().)^.
21f0: 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74  **.** See the [t
2200: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64  hreading mode] d
2210: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2220: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2230: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  rmation..*/.int 
2240: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2250: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  fe(void);../*.**
2260: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
2270: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48  ase Connection H
2280: 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44  andle.** KEYWORD
2290: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
22a0: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
22b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
22c0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
22d0: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
22e0: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
22f0: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  y a pointer to a
2300: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a  n instance of.**
2310: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75   the opaque stru
2320: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c  cture named "sql
2330: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73  ite3".  It is us
2340: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66  eful to think of
2350: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70   an sqlite3.** p
2360: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a  ointer as an obj
2370: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ect.  The [sqlit
2380: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2390: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
23a0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
23b0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
23c0: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f  faces are its co
23d0: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20  nstructors, and 
23e0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
23f0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2400: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72  3_close_v2()] ar
2410: 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  e its destructor
2420: 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  s.  There are ma
2430: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65  ny other.** inte
2440: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
2450: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2460: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
2470: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2480: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
2490: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
24a0: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
24b0: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
24c0: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
24d0: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
24e0: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
24f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
2500: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
2510: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
2520: 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a  Integer Types.**
2530: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
2540: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  e_int64 sqlite_u
2550: 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61  int64.**.** Beca
2560: 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20  use there is no 
2570: 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77  cross-platform w
2580: 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34  ay to specify 64
2590: 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70  -bit integer typ
25a0: 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63  es.** SQLite inc
25b0: 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66  ludes typedefs f
25c0: 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  or 64-bit signed
25d0: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e   and unsigned in
25e0: 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  tegers..**.** Th
25f0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
2600: 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  and sqlite3_uint
2610: 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65  64 are the prefe
2620: 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69  rred type defini
2630: 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71  tions..** The sq
2640: 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73  lite_int64 and s
2650: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2660: 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  es are supported
2670: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a   for backwards.*
2680: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
2690: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  only..**.** ^The
26a0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
26b0: 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  nd sqlite_int64 
26c0: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20  types can store 
26d0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a  integer values.*
26e0: 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33  * between -92233
26f0: 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61  72036854775808 a
2700: 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35  nd +922337203685
2710: 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76  4775807 inclusiv
2720: 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
2730: 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73  te3_uint64 and s
2740: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2750: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2760: 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20  eger values .** 
2770: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31  between 0 and +1
2780: 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31  8446744073709551
2790: 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a  615 inclusive..*
27a0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
27b0: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
27c0: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
27d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
27e0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
27f0: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
2800: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2810: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
2820: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2830: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2840: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2850: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2860: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2870: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2880: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2890: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
28a0: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
28b0: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
28c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
28d0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
28e0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
28f0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2900: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2910: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2920: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2930: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2940: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2950: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2960: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2970: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2980: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2990: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
29a0: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
29b0: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
29c0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
29d0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
29e0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
29f0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2a00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2a10: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2a20: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
2a30: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2a40: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2a50: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2a60: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2a70: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2a80: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2a90: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2aa0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ab0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2ac0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2ad0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2ae0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2af0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2b00: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2b10: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2b20: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2b30: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2b40: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2b50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b60: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2b70: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2b80: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2b90: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ba0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2bb0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2bc0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2bd0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2c00: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2c10: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2c20: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2c30: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2c40: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2c50: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2c60: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2c70: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2c80: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2c90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ca0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2cb0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2cc0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2cd0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2ce0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2cf0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2d00: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2d10: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2d20: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2d30: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2d40: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2d50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2d60: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2d70: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2d80: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2d90: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2da0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2db0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2dc0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2dd0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2de0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2df0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2e00: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
2e10: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e20: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2e30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e40: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
2e50: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
2e60: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
2e70: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
2e80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
2e90: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
2ea0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
2eb0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
2ec0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
2ed0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
2ee0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
2ef0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
2f00: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
2f10: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
2f20: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
2f30: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f50: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
2f60: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
2f70: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f80: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
2f90: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
2fa0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
2fb0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
2fc0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
2fd0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
2fe0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
2ff0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3000: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3010: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3020: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3030: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3040: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3050: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3060: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3070: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3080: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3090: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
30a0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
30b0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
30c0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
30d0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
30e0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
30f0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3100: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3110: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3120: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3130: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3140: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3150: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3160: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3170: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3180: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3190: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
31a0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
31b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
31c0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
31d0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
31e0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
31f0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3200: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3210: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3220: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3230: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3240: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3250: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3260: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
3270: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
3280: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
3290: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
32a0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
32b0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
32c0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
32d0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
32e0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
32f0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3300: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3310: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3320: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3330: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3340: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3350: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3360: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
3370: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
3380: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
3390: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
33a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
33b0: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
33c0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
33d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
33e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
33f0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
3400: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
3410: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
3420: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
3430: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
3440: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
3450: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3460: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3470: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3480: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3490: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
34a0: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
34b0: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
34c0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
34d0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
34e0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
34f0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
3500: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
3510: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
3520: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3530: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
3540: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
3550: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3560: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3570: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3580: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3590: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
35a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
35b0: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
35c0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
35d0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
35e0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
35f0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
3600: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3610: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3620: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
3630: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
3640: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
3650: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3660: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3670: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3680: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3690: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
36a0: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
36b0: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
36c0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
36d0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
36e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
36f0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
3700: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
3710: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3720: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
3730: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
3740: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
3750: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3760: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3770: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3780: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3790: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
37a0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
37b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
37c0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
37d0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
37e0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
37f0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
3800: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3810: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
3820: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
3830: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
3840: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
3850: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3860: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3870: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3880: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3890: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
38a0: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
38b0: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
38c0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
38d0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
38e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
38f0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3900: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3910: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3920: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3930: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3940: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3950: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3960: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3970: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3980: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3990: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
39a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
39b0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
39c0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
39d0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
39e0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
39f0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3a00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3a10: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3a20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3a30: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3a40: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3a50: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3a60: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3a70: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3a80: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3a90: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3aa0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3ab0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3ac0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3ad0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3ae0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3af0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3b00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3b10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3b20: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3b30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3b40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3b50: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3b60: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3b70: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3b80: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3b90: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ba0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3bb0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3bc0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3bd0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3be0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3c00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3c10: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3c20: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3c30: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3c40: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3c50: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3c60: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3c70: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3c80: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3c90: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3ca0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3cb0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3cc0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3cd0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3ce0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3cf0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3d00: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3d10: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
3d20: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
3d30: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
3d40: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
3d50: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3d60: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3d70: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3d80: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3d90: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3da0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3db0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3dc0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3dd0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3de0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3df0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
3e00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e10: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
3e20: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3e30: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3e40: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
3e50: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3e70: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3e80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e90: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
3ea0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3eb0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3ec0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3ed0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3ef0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3f00: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3f10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3f20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3f30: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3f40: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3f50: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3f60: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3f70: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3f80: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3f90: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3fa0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
3fb0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
3fc0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
3fd0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ff0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4000: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4010: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4040: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4050: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4060: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4070: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4080: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4090: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
40d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
40e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
40f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4110: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4120: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4130: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4140: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4150: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4160: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4170: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4180: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4190: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
41a0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
41b0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
41c0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
41d0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
41e0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
41f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4200: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4210: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4220: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4230: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4240: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4250: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4260: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4270: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4280: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4290: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
42a0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
42b0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
42c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
42d0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
42e0: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
42f0: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
4300: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4310: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4320: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4330: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4340: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4350: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4360: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4370: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4380: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4390: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
43a0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
43b0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
43c0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
43d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43e0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
43f0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4400: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4410: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4420: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4430: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4440: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4450: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4460: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4470: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4480: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
44b0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
44c0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
44d0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
44e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
44f0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4500: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4510: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4520: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4540: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4550: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4560: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4570: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4580: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4590: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
45a0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
45b0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
45c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
45d0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
45e0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
45f0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4600: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4610: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4620: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4630: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4640: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4650: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4660: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4670: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4680: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4690: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
46a0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
46b0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
46c0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
46d0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
46e0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
46f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4700: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4710: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
4720: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
4730: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4740: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4750: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4760: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4770: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4780: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4790: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
47a0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
47b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47c0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
47d0: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
47e0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
47f0: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4800: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4810: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4820: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4830: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4840: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4850: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4860: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4880: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4890: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
48a0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
48b0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
48c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
48d0: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
48e0: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
48f0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4900: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4910: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4920: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4930: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
4940: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4950: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4960: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4970: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4980: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
49a0: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
49b0: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
49c0: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
49d0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
49e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
49f0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4a00: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4a10: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4a20: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4a30: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4a40: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4a50: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4a60: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4a70: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4a80: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4a90: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4aa0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4ab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ac0: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4ad0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4ae0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4af0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4b00: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4b10: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4b20: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4b30: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4b40: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4b50: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4b60: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4b70: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4b80: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4b90: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4ba0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4bb0: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4bc0: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4bd0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4be0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4bf0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4c00: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4c10: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4c20: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4c30: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4c40: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4c50: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4c60: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4c70: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4c80: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4c90: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4ca0: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4cb0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4cc0: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4cd0: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4ce0: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4cf0: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4d00: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4d10: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4d20: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
4d30: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
4d40: 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65  ese [extended re
4d50: 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20  sult codes] are 
4d60: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
4d70: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
4d80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4d90: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
4da0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4db0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
4dc0: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f  codes()] API.  O
4dd0: 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20  r, the extended 
4de0: 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  code for.** the 
4df0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f  most recent erro
4e00: 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  r can be obtaine
4e10: 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
4e20: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
4e30: 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  code()]..*/.#def
4e40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e50: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
4e60: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e70: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
4e80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4e90: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
4ea0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4eb0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
4ec0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
4ed0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
4ee0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4ef0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
4f00: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
4f10: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
4f20: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f30: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
4f40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
4f50: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
4f60: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f70: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
4f80: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
4f90: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
4fa0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
4fb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4fc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
4fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4fe0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
4ff0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5000: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
5010: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5020: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
5030: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5040: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
5050: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5060: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
5070: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5080: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
5090: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
50b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50c0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
50d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
50f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5100: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
5110: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5120: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
5130: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5140: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
5150: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5160: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
5170: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5180: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
5190: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
51a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
51b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51c0: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
51d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
51f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5200: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
5210: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5220: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
5230: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5240: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
5250: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
5260: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
5270: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5280: 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20  E_IOERR_SHMOPEN 
5290: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38  E_IOERR | (18<<8
52b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
52c0: 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20  E_IOERR_SHMSIZE 
52d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38  E_IOERR | (19<<8
52f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5300: 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20  E_IOERR_SHMLOCK 
5310: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5320: 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38  E_IOERR | (20<<8
5330: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5340: 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20  E_IOERR_SHMMAP  
5350: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5360: 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38  E_IOERR | (21<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20  E_IOERR_SEEK    
5390: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38  E_IOERR | (22<<8
53b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
53c0: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e  E_IOERR_DELETE_N
53d0: 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54  OENT      (SQLIT
53e0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38  E_IOERR | (23<<8
53f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5400: 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20  E_IOERR_MMAP    
5410: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5420: 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38  E_IOERR | (24<<8
5430: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5440: 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50  E_IOERR_GETTEMPP
5450: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5460: 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38  E_IOERR | (25<<8
5470: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5480: 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48  E_IOERR_CONVPATH
5490: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
54a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38  E_IOERR | (26<<8
54b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
54c0: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
54d0: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
54e0: 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c  E_LOCKED |  (1<<
54f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5500: 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59  TE_BUSY_RECOVERY
5510: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5520: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c  TE_BUSY   |  (1<
5530: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5540: 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f  ITE_BUSY_SNAPSHO
5550: 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  T           (SQL
5560: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32  ITE_BUSY   |  (2
5570: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5580: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5590: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
55a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
55b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
55c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
55d0: 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28  ISDIR          (
55e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
55f0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5600: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5610: 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20  N_FULLPATH      
5620: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5630: 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  N | (3<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5650: 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  PEN_CONVPATH    
5660: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5670: 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  PEN | (4<<8)).#d
5680: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
5690: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20  RUPT_VTAB       
56a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52       (SQLITE_COR
56b0: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  RUPT | (1<<8)).#
56c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
56d0: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20  ADONLY_RECOVERY 
56e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
56f0: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29  ADONLY | (1<<8))
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43  READONLY_CANTLOC
5720: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5730: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38  READONLY | (2<<8
5740: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5750: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42  E_READONLY_ROLLB
5760: 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  ACK       (SQLIT
5770: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c  E_READONLY | (3<
5780: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5790: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d  ITE_READONLY_DBM
57a0: 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c  OVED        (SQL
57b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
57c0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
57d0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
57e0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
57f0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5800: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5810: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5820: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5830: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5840: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5850: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5860: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5870: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5880: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5890: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
58a0: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
58b0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
58c0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
58d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58e0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
58f0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5900: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5910: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5920: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5930: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
5940: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5950: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5960: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5970: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
5980: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5990: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
59a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59b0: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
59c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
59d0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
59e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
59f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
5a00: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
5a20: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a30: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a40: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a60: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5a70: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5a80: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
5a90: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5aa0: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
5ab0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5ac0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
5ad0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
5ae0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
5af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5b00: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
5b10: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
5b20: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
5b30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
5b40: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
5b50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
5b60: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
5b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
5b80: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
5b90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
5ba0: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  TH | (1<<8))../*
5bb0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
5bc0: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
5bd0: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
5be0: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
5bf0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
5c00: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
5c10: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
5c20: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5c30: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
5c40: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
5c50: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5c60: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5c70: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
5c80: 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  hod..*/.#define 
5c90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5ca0: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
5cb0: 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66  0000001  /* Ok f
5cc0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5cd0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ce0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5cf0: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
5d00: 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66  0000002  /* Ok f
5d10: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d20: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
5d40: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
5d50: 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66  0000004  /* Ok f
5d60: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d70: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
5d90: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
5da0: 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20  0000008  /* VFS 
5db0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5dc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
5dd0: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
5de0: 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20  0000010  /* VFS 
5df0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f  SQLITE_OPEN_AUTO
5e10: 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30  PROXY        0x0
5e20: 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20  0000020  /* VFS 
5e30: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
5e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5e60: 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66  0000040  /* Ok f
5e70: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5e80: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5e90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f  SQLITE_OPEN_MEMO
5ea0: 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30  RY           0x0
5eb0: 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66  0000080  /* Ok f
5ec0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5ed0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ee0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5ef0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f00: 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20  0000100  /* VFS 
5f10: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5f30: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f40: 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20  0000200  /* VFS 
5f50: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
5f70: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30  SIENT_DB     0x0
5f80: 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20  0000400  /* VFS 
5f90: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fa0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5fb0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
5fc0: 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20  0000800  /* VFS 
5fd0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fe0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5ff0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
6000: 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20  0001000  /* VFS 
6010: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6020: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
6030: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
6040: 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20  0002000  /* VFS 
6050: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6060: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
6070: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
6080: 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20  0004000  /* VFS 
6090: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
60a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
60b0: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30  TEX          0x0
60c0: 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0008000  /* Ok f
60d0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
60e0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
60f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
6100: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30  MUTEX        0x0
6110: 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0010000  /* Ok f
6120: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6130: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6140: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
6150: 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30  EDCACHE      0x0
6160: 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0020000  /* Ok f
6170: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6180: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6190: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
61a0: 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30  ATECACHE     0x0
61b0: 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0040000  /* Ok f
61c0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
61d0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
61e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20  SQLITE_OPEN_WAL 
61f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6200: 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20  0080000  /* VFS 
6210: 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65  only */../* Rese
6220: 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20  rved:           
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6240: 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a  00F00000 */../*.
6250: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
6260: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
6270: 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  ics.**.** The xD
6280: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6290: 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  tics method of t
62a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
62b0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
62c0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
62d0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
62e0: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a  vector of these.
62f0: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
6300: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
6310: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
6320: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
6330: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
6340: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
6350: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
6360: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6370: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
6380: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6390: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
63a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
63b0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
63c0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
63d0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
63e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
63f0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6400: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6410: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6420: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6430: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6440: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6450: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6460: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6470: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6480: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6490: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
64a0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
64b0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
64c0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
64d0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
64e0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
64f0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6500: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6510: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6520: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6530: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6540: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6550: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6560: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6570: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6580: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6590: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
65a0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
65b0: 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c  rite().  The SQL
65c0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
65d0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72  AFE_OVERWRITE pr
65e0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
65f0: 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f  t.** after reboo
6600: 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72  t following a cr
6610: 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73  ash or power los
6620: 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65  s, the only byte
6630: 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74  s in a.** file t
6640: 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e  hat were written
6650: 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74   at the applicat
6660: 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20  ion level might 
6670: 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  have changed.** 
6680: 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e  and that adjacen
6690: 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79  t bytes, even by
66a0: 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  tes within the s
66b0: 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a  ame sector are.*
66c0: 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  * guaranteed to 
66d0: 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  be unchanged.  T
66e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
66f0: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6700: 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e  _OPEN.** flag in
6710: 64 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69  dicate that a fi
6720: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c  le cannot be del
6730: 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20  eted when open. 
6740: 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49   The.** SQLITE_I
6750: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66  OCAP_IMMUTABLE f
6760: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
6770: 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f  at the file is o
6780: 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  n.** read-only m
6790: 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20  edia and cannot 
67a0: 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20  be changed even 
67b0: 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74  by processes wit
67c0: 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72  h.** elevated pr
67d0: 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65  ivileges..*/.#de
67e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
67f0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
6800: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6810: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6820: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6830: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6840: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6850: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6860: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6870: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6880: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6890: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
68a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
68b0: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
68c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
68d0: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
68e0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
68f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6900: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
6910: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6920: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6940: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
6950: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
6960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6970: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
6980: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6990: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
69a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
69b0: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
69c0: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
69d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
69e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
69f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6a00: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a10: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6a20: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
6a30: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
6a40: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6a50: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6a60: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
6a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a80: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6a90: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
6aa0: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
6ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6ac0: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  UTABLE          
6ad0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a      0x00002000..
6ae0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6af0: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
6b00: 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  els.**.** SQLite
6b10: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
6b20: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
6b30: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
6b40: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
6b50: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
6b60: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
6b70: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
6b80: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
6b90: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6ba0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
6bb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6bc0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6be0: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
6bf0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
6c00: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
6c10: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
6c20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6c30: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
6c40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6c50: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
6c60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6c70: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
6c80: 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a   Type Flags.**.*
6c90: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
6ca0: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
6cb0: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
6cc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6cd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
6ce0: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
6cf0: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
6d00: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6d10: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
6d20: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
6d30: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
6d40: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
6d50: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
6d60: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
6d70: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
6d80: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
6d90: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
6da0: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
6db0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
6dc0: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
6dd0: 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  . If the lower f
6de0: 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20  our bits of the 
6df0: 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51  flag.** equal SQ
6e00: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6e10: 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20  , that means to 
6e20: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
6e30: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a  () semantics..**
6e40: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6e50: 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51  ur bits equal SQ
6e60: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6e70: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  that means.** to
6e80: 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74   use Mac OS X st
6e90: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
6ea0: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
6eb0: 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f  .**.** Do not co
6ec0: 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45  nfuse the SQLITE
6ed0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6ee0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6ef0: 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20  L flags.** with 
6f00: 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  the [PRAGMA sync
6f10: 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20  hronous]=NORMAL 
6f20: 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  and [PRAGMA sync
6f30: 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a  hronous]=FULL.**
6f40: 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20   settings.  The 
6f50: 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61  [synchronous pra
6f60: 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20  gma] determines 
6f70: 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68  when calls to th
6f80: 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d  e.** xSync VFS m
6f90: 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20  ethod occur and 
6fa0: 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c  applies uniforml
6fb0: 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61  y across all pla
6fc0: 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53  tforms..** The S
6fd0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6fe0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6ff0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74  C_FULL flags det
7000: 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e  ermine how.** en
7010: 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72  ergetic or rigor
7020: 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20  ous or forceful 
7030: 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69  the sync operati
7040: 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f  ons are and.** o
7050: 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65  nly make a diffe
7060: 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58  rence on Mac OSX
7070: 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74   for the default
7080: 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a   SQLite code..**
7090: 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46   (Third-party VF
70a0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
70b0: 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b  s might also mak
70c0: 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
70d0: 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
70e0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
70f0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7100: 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20  FULL, but among 
7110: 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67  the.** operating
7120: 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c   systems nativel
7130: 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  y supported by S
7140: 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20  QLite, only Mac 
7150: 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f  OSX.** cares abo
7160: 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  ut the differenc
7170: 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e.).*/.#define S
7180: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7190: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
71a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71b0: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
71c0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
71d0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
71e0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
71f0: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
7200: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
7210: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
7220: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
7230: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7240: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
7250: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
7260: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
7270: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63  fs | OS interfac
7280: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76  e layer].  Indiv
7290: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
72a0: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ce.** implementa
72b0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
72c0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
72d0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
72e0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
72f0: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
7300: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
7310: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
7320: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
7330: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
7340: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7350: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
7360: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
7370: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
7380: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
7390: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
73a0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
73b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
73c0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
73d0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
73e0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
73f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7400: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
7410: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
7420: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
7430: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7440: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
7450: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
7460: 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
7470: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
7480: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7490: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
74a0: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
74b0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
74c0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
74d0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
74e0: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
74f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7500: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
7510: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
7520: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
7530: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
7540: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
7550: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
7560: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
7570: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
7580: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
7590: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
75a0: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
75b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
75c0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
75d0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
75e0: 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74  n] method sets t
75f0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7600: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7610: 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55   .** to a non-NU
7620: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
7630: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f   the sqlite3_io_
7640: 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d  methods.xClose m
7650: 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20  ethod.** may be 
7660: 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20  invoked even if 
7670: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7680: 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64  .xOpen] reported
7690: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
76a0: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
76b0: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
76c0: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
76d0: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
76e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
76f0: 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74  pen].** is for t
7700: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7710: 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68  xOpen] to set th
7720: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7730: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a  Methods element.
7740: 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ** to NULL..**.*
7750: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
7760: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
7770: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
7780: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
7790: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
77a0: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
77b0: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
77c0: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
77d0: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
77e0: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
77f0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7800: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
7810: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7820: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
7830: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
7840: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
7850: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
7860: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
7870: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
7880: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
7890: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
78a0: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
78b0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
78c0: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
78d0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
78e0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
78f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7900: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7910: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7920: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
7930: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7940: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
7950: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7960: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
7970: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
7980: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
7990: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
79a0: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
79b0: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
79c0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
79d0: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
79e0: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
79f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
7a00: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
7a10: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
7a20: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
7a30: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
7a40: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
7a50: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
7a60: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
7a70: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
7a80: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
7a90: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
7aa0: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
7ab0: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
7ac0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7ad0: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
7ae0: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
7af0: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
7b00: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
7b10: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
7b20: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
7b30: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
7b40: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7b50: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
7b60: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
7b70: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
7b80: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
7b90: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
7ba0: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
7bb0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
7bc0: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
7bd0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
7be0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
7bf0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
7c00: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
7c10: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
7c20: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
7c30: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
7c40: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
7c50: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
7c60: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
7c70: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
7c80: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
7c90: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
7ca0: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
7cb0: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
7cc0: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
7cd0: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
7ce0: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
7cf0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
7d00: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
7d10: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
7d20: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
7d30: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
7d40: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
7d50: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
7d60: 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63  se..** A [file c
7d70: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c  ontrol opcodes |
7d80: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
7d90: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
7da0: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
7db0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
7dc0: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
7dd0: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
7de0: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
7df0: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
7e00: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
7e10: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
7e20: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
7e30: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
7e40: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
7e50: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
7e60: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7e70: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
7e80: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
7e90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
7ea0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
7eb0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
7ec0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
7ed0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
7ee0: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
7ef0: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
7f00: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
7f10: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
7f20: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
7f30: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
7f40: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
7f50: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
7f60: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
7f70: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
7f80: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7f90: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
7fa0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
7fb0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
7fc0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
7fd0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
7fe0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7ff0: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
8000: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8010: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
8020: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8030: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
8040: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8050: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
8060: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8070: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
8080: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8090: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
80a0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
80b0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
80c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
80d0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
80e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
80f0: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
8100: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8110: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
8120: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8130: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8140: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
8150: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8160: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
8170: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
8180: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
8190: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
81a0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
81b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
81c0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
81d0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
81e0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
81f0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
8200: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
8210: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
8220: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
8230: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
8240: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
8250: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8260: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8270: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
8280: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
8290: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
82a0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
82b0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
82c0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
82d0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
82e0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
82f0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
8300: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
8310: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8320: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
8330: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
8340: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
8350: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
8360: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
8370: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
8380: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
8390: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
83a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
83b0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
83c0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
83d0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
83e0: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
83f0: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
8400: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
8410: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
8420: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
8430: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
8440: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
8450: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
8460: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
8470: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
8480: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
8490: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
84a0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
84b0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
84c0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
84d0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
84e0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
84f0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
8500: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
8510: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
8520: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
8530: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
8540: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
8550: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8560: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8570: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
8580: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
8590: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
85a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
85b0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
85c0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
85d0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
85e0: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
85f0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
8600: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
8610: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
8620: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
8630: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8640: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
8650: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
8660: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8670: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
8680: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8690: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
86a0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
86b0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
86c0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
86d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
86e0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
86f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
8700: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
8710: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
8720: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8730: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
8740: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8750: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8760: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8770: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8780: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
8790: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
87a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
87b0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
87c0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
87d0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
87e0: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
87f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8800: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
8810: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
8820: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
8830: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8840: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
8850: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8860: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
8870: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8880: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8890: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
88a0: 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29  .  int (*xFetch)
88b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88c0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
88d0: 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76  fst, int iAmt, v
88e0: 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74  oid **pp);.  int
88f0: 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c   (*xUnfetch)(sql
8900: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8910: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8920: 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20   void *p);.  /* 
8930: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8940: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8950: 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 3 */.  /* Ad
8960: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
8970: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8980: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
8990: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
89a0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
89b0: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
89c0: 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  codes.** KEYWORD
89d0: 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  S: {file control
89e0: 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20   opcodes} {file 
89f0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a  control opcode}.
8a00: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
8a10: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
8a20: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
8a30: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
8a40: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
8a50: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
8a60: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
8a70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
8a80: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8a90: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
8aa0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
8ab0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8ac0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8ad0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
8ae0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
8af0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
8b00: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
8b10: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
8b20: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
8b30: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
8b40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
8b50: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
8b60: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
8b70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8b80: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
8b90: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
8ba0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8bb0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
8bc0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
8bd0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
8be0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
8bf0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
8c00: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
8c10: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
8c20: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
8c30: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
8c40: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
8c50: 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a  fined..** <ul>.*
8c60: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8c70: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8c80: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8c90: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8ca0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8cb0: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8cc0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8cd0: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8ce0: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8cf0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8d00: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8d10: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8d20: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8d30: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8d40: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8d50: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8d60: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8d70: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8d80: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8d90: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8da0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8db0: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8dc0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8dd0: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8de0: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8df0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8e00: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8e10: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8e20: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8e30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8e40: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8e50: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8e60: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
8e70: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
8e80: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
8e90: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8ea0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
8eb0: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
8ec0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
8ed0: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
8ee0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
8ef0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
8f00: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
8f10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
8f20: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
8f30: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
8f40: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
8f50: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
8f60: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
8f70: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
8f80: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
8f90: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
8fa0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8fb0: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8fc0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
8fd0: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
8fe0: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
8ff0: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9000: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9010: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9020: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
9030: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9040: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
9050: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9060: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9070: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9080: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9090: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
90a0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
90b0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
90c0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
90d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
90e0: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
90f0: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9100: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
9110: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
9120: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9130: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
9140: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
9150: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
9160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9170: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9180: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9190: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
91a0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
91b0: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
91c0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
91d0: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
91e0: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
91f0: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9200: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
9210: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
9220: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
9230: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
9240: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
9250: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
9260: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9270: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9280: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9290: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
92a0: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
92b0: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
92c0: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
92d0: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
92e0: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
92f0: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9300: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
9310: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
9320: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
9330: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
9340: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
9350: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
9360: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
9370: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9380: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9390: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
93a0: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
93b0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
93c0: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
93d0: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
93e0: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
93f0: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9400: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
9410: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
9420: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
9430: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
9440: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
9450: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9460: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9470: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9480: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
9490: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
94a0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
94b0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
94c0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
94d0: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
94e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
94f0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9500: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9510: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
9520: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
9530: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9540: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
9550: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
9560: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
9570: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9580: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
9590: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
95a0: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
95b0: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
95c0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
95d0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
95e0: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
95f0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9600: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
9610: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
9620: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
9630: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9640: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9650: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9660: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
9670: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9680: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9690: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
96a0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
96b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
96c0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
96d0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
96e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
96f0: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9700: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9710: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9720: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9730: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9740: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
9750: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
9760: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9770: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9780: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9790: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
97a0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
97b0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
97c0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
97d0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
97e0: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
97f0: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9800: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9810: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9820: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9830: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9840: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
9850: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
9860: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9870: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9880: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9890: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
98a0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
98b0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
98c0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
98d0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
98e0: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
98f0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9900: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9910: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9920: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9930: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9940: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9950: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9960: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9970: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9980: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9990: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
99a0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
99b0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
99c0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
99d0: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
99e0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
99f0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9a00: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9a10: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9a20: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9a30: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9a40: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9a50: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9a60: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9a70: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9a80: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9a90: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9aa0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9ab0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9ac0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9ad0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9ae0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9af0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9b00: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9b10: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9b20: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9b30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9b40: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9b50: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9b60: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9b70: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9b80: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9b90: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9ba0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9bb0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9bc0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9bd0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9be0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9bf0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9c00: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9c10: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9c20: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9c30: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9c40: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9c50: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9c60: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9c70: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9c80: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9c90: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9ca0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9cb0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9cc0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9cd0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9ce0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9cf0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9d00: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9d10: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9d20: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9d30: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9d40: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9d50: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9d60: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9d70: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9d80: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9d90: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9da0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9db0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9dc0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9dd0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9de0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9df0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9e00: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9e10: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9e20: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9e30: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9e40: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9e50: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9e60: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9e70: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9e80: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9e90: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9ea0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
9eb0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
9ec0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9ed0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9ee0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
9ef0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9f00: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9f10: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9f20: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9f30: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9f40: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
9f50: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
9f60: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
9f70: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
9f80: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
9f90: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
9fa0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
9fb0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
9fc0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
9fd0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
9fe0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
9ff0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a000: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a010: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a020: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a030: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a040: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a050: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a060: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a070: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a080: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a090: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a0a0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a0b0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a0c0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a0d0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a0e0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a0f0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a100: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a110: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a120: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a130: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a140: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a150: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a160: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a170: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a180: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a190: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a1a0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a1b0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a1c0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a1d0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a1e0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a1f0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a200: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a210: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a220: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a230: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a240: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a250: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a260: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a270: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a280: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a290: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a2a0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a2b0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a2c0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a2d0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a2e0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a2f0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a300: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a310: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a320: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a330: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a340: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a350: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a360: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a370: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a380: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a390: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a3a0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a3b0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a3c0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a3d0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a3e0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a3f0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a400: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a410: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a420: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a430: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a440: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a450: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a460: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a470: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a480: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a490: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a4a0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a4b0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a4c0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a4d0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a4e0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a4f0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a500: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a510: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a520: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a530: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a540: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a550: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a560: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a570: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a580: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a590: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a5a0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a5b0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a5c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a5d0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a5e0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a5f0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a600: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a610: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a620: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a630: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a640: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a650: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a660: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a670: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a680: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a690: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a6a0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a6b0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a6c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a6d0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a6e0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a6f0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a700: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a710: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a720: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a730: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a740: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a750: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a760: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a770: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a780: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a790: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a7a0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a7b0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a7c0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a7d0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a7e0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a7f0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a800: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a810: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a820: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a830: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a840: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a850: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a860: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a870: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a880: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a890: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a8a0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a8b0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
a8c0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
a8d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a8e0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
a8f0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
a900: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
a910: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
a920: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
a930: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
a940: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
a950: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
a960: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a970: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a980: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a990: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
a9a0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
a9b0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
a9c0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
a9d0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
a9e0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
a9f0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
aa00: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
aa10: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
aa20: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
aa30: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
aa40: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
aa50: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
aa60: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa70: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
aa80: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
aa90: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
aaa0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
aab0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
aac0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
aad0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
aae0: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
aaf0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
ab00: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ab10: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
ab20: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
ab30: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
ab40: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
ab50: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
ab60: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
ab70: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
ab80: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
ab90: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
aba0: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
abb0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
abc0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
abd0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
abe0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
abf0: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
ac00: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
ac10: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
ac20: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
ac30: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
ac40: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
ac50: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
ac60: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
ac70: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
ac80: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
ac90: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
aca0: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
acb0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
acc0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
acd0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
ace0: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
acf0: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
ad00: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
ad10: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
ad20: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
ad30: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
ad40: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
ad50: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
ad60: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
ad70: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
ad80: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
ad90: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
ada0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
adb0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
adc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
add0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
ade0: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
adf0: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
ae00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
ae10: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
ae20: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
ae30: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
ae40: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
ae50: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
ae60: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
ae70: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
ae80: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
ae90: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
aea0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
aeb0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
aec0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
aed0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
aee0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
aef0: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
af00: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
af10: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
af20: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
af30: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
af40: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
af50: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
af60: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
af70: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
af80: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
af90: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
afa0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
afb0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
afc0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
afd0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
afe0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
aff0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b000: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
b010: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
b020: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
b030: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
b040: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
b050: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
b060: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b070: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
b080: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
b090: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
b0a0: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
b0b0: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
b0c0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
b0d0: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
b0e0: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
b0f0: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
b100: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
b110: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
b120: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
b130: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
b140: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
b150: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
b160: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
b170: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
b180: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
b190: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
b1a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
b1b0: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
b1c0: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
b1d0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
b1e0: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
b1f0: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
b200: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
b210: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b220: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
b230: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b240: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
b250: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
b260: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
b270: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
b280: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
b290: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
b2a0: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
b2b0: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
b2c0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
b2d0: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
b2e0: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
b2f0: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
b300: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b310: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
b320: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
b330: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
b340: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
b350: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
b360: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
b370: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
b380: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
b390: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
b3a0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b3b0: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
b3c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b3d0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
b3e0: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
b3f0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b400: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
b410: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
b420: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
b430: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
b440: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
b450: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
b460: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
b470: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
b480: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
b490: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
b4a0: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
b4b0: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
b4c0: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
b4d0: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
b4e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b4f0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
b500: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
b510: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b520: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
b530: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
b540: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
b550: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
b560: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
b570: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
b580: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
b590: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
b5a0: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
b5b0: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
b5c0: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
b5d0: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
b5e0: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
b5f0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
b600: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
b610: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
b620: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
b630: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </ul>.*/.#defi
b640: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b650: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
b660: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
b670: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
b680: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
b690: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
b6a0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
b6b0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
b6c0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
b6d0: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e  SQLITE_LAST_ERRN
b6e0: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  O               
b6f0: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
b700: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
b710: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  _HINT           
b720: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
b730: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
b740: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
b750: 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
b760: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
b770: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
b780: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
b790: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
b7a0: 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20  ITTED           
b7b0: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
b7c0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
b7d0: 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20  _RETRY          
b7e0: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
b7f0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
b800: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30  AL            10
b810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b820: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20  FCNTL_OVERWRITE 
b830: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a               11.
b840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b850: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20  CNTL_VFSNAME    
b860: 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23              12.#
b870: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b880: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
b890: 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64  ERWRITE    13.#d
b8a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b8b0: 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TL_PRAGMA       
b8c0: 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65            14.#de
b8d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b8e0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20  L_BUSYHANDLER   
b8f0: 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66           15.#def
b900: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b910: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20  _TEMPFILENAME   
b920: 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69          16.#defi
b930: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b940: 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20  MMAP_SIZE       
b950: 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e         18.#defin
b960: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
b970: 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20  RACE            
b980: 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65        19.#define
b990: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41   SQLITE_FCNTL_HA
b9a0: 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20  S_MOVED         
b9b0: 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20       20.#define 
b9c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
b9d0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
b9e0: 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53      21.#define S
b9f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
ba00: 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20  IT_PHASETWO     
ba10: 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51     22.#define SQ
ba20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
ba30: 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _SET_HANDLE     
ba40: 20 20 32 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    23../*.** CAPI
ba50: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
ba60: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
ba70: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
ba80: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
ba90: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
baa0: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
bab0: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
bac0: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
bad0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
bae0: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
baf0: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
bb00: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
bb10: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
bb20: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
bb30: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
bb40: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
bb50: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
bb60: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
bb70: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
bb80: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
bb90: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
bba0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
bbb0: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
bbc0: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
bbd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
bbe0: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a  nterface Object.
bbf0: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
bc00: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  e of the sqlite3
bc10: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69  _vfs object defi
bc20: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
bc30: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  e between.** the
bc40: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
bc50: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
bc60: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
bc70: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
bc80: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
bc90: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
bca0: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
bcb0: 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65  le system".  See
bcc0: 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56  .** the [VFS | V
bcd0: 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  FS documentation
bce0: 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e  ] for further in
bcf0: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
bd00: 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   The value of th
bd10: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
bd20: 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20   is initially 1 
bd30: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
bd40: 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76  r in.** future v
bd50: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
bd60: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
bd70: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
bd80: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
bd90: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
bda0: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
bdb0: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e  is increased.  N
bdc0: 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72  ote that the str
bdd0: 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65  ucture.** of the
bde0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
bdf0: 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74  ect changes in t
be00: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
be10: 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  etween.** SQLite
be20: 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61   version 3.5.9 a
be30: 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74  nd 3.6.0 and yet
be40: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
be50: 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d  eld was not.** m
be60: 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  odified..**.** T
be70: 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c  he szOsFile fiel
be80: 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  d is the size of
be90: 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20   the subclassed 
bea0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a  [sqlite3_file].*
beb0: 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64  * structure used
bec0: 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d   by this VFS.  m
bed0: 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65  xPathname is the
bee0: 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
bef0: 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65  of.** a pathname
bf00: 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a   in this VFS..**
bf10: 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73  .** Registered s
bf20: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
bf30: 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61  ts are kept on a
bf40: 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72   linked list for
bf50: 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e  med by.** the pN
bf60: 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ext pointer.  Th
bf70: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  e [sqlite3_vfs_r
bf80: 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e  egister()].** an
bf90: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  d [sqlite3_vfs_u
bfa0: 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74  nregister()] int
bfb0: 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74  erfaces manage t
bfc0: 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61  his list.** in a
bfd0: 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79   thread-safe way
bfe0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
bff0: 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65  vfs_find()] inte
c000: 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65  rface.** searche
c010: 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69  s the list.  Nei
c020: 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  ther the applica
c030: 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68  tion code nor th
c040: 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65  e VFS.** impleme
c050: 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  ntation should u
c060: 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  se the pNext poi
c070: 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
c080: 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74  pNext field is t
c090: 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e  he only field in
c0a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c0b0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68  .** structure th
c0c0: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65  at SQLite will e
c0d0: 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c  ver modify.  SQL
c0e0: 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63  ite will only ac
c0f0: 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66  cess.** or modif
c100: 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69  y this field whi
c110: 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72  le holding a par
c120: 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d  ticular static m
c130: 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70  utex..** The app
c140: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
c150: 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79  never modify any
c160: 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65  thing within the
c170: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
c180: 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20  object once the 
c190: 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20  object has been 
c1a0: 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a  registered..**.*
c1b0: 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c  * The zName fiel
c1c0: 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65  d holds the name
c1d0: 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75   of the VFS modu
c1e0: 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75  le.  The name mu
c1f0: 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20  st.** be unique 
c200: 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d  across all VFS m
c210: 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  odules..**.** [[
c220: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
c230: 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  n]].** ^SQLite g
c240: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
c250: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
c260: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a  ameter to xOpen.
c270: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ** is either a N
c280: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73  ULL pointer or s
c290: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a  tring obtained.*
c2a0: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68  * from xFullPath
c2b0: 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f  name() with an o
c2c0: 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61  ptional suffix a
c2d0: 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73  dded..** ^If a s
c2e0: 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74  uffix is added t
c2f0: 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  o the zFilename 
c300: 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69  parameter, it wi
c310: 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66  ll.** consist of
c320: 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68   a single "-" ch
c330: 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64  aracter followed
c340: 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e   by no more than
c350: 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65  .** 11 alphanume
c360: 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63  ric and/or "-" c
c370: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53  haracters..** ^S
c380: 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75  QLite further gu
c390: 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a  arantees that.**
c3a0: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
c3b0: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
c3c0: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
c3d0: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
c3e0: 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20  led. Because of 
c3f0: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
c400: 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tence,.** the [s
c410: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
c420: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
c430: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
c440: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
c450: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
c460: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
c470: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
c480: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
c490: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
c4a0: 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  o xOpen is a NUL
c4b0: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
c4c0: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
c4d0: 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ent its own temp
c4e0: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
c4f0: 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65  he file.  ^Whene
c500: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
c510: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
c520: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
c530: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
c540: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
c550: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
c560: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
c570: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
c580: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
c590: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
c5a0: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
c5b0: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
c5c0: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
c5d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
c5e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
c5f0: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
c600: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
c610: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
c620: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
c630: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
c640: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
c650: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
c660: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
c670: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
c680: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
c690: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
c6a0: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
c6b0: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
c6c0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
c6d0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
c6e0: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
c6f0: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
c700: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51   set..**.** ^(SQ
c710: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
c720: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
c730: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
c740: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
c750: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
c760: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
c770: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
c780: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
c790: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
c7a0: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
c7b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
c7c0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
c7d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c7e0: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
c7f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
c800: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
c810: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
c820: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
c830: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c840: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
c850: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
c860: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
c870: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
c880: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57    [SQLITE_OPEN_W
c890: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  AL].** </ul>)^.*
c8a0: 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
c8b0: 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
c8c0: 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
c8d0: 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
c8e0: 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  o.** change the 
c8f0: 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74  way it deals wit
c900: 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78  h files.  For ex
c910: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
c920: 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f  ation.** that do
c930: 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75  es not care abou
c940: 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79  t crash recovery
c950: 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67   or rollback mig
c960: 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f  ht make.** the o
c970: 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c  pen of a journal
c980: 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20   file a no-op.  
c990: 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a  Writes to this j
c9a0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20  ournal would.** 
c9b0: 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20  also be no-ops, 
c9c0: 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20  and any attempt 
c9d0: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
c9e0: 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  nal would return
c9f0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  .** SQLITE_IOERR
ca00: 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  .  Or the implem
ca10: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
ca20: 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20  ecognize that a 
ca30: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
ca40: 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70   will be doing p
ca50: 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
ca60: 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
ca70: 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a  tes in a random.
ca80: 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74  ** order and set
ca90: 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
caa0: 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
cab0: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  y..**.** SQLite 
cac0: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
cad0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
cae0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
caf0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a   xOpen method:.*
cb00: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
cb10: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  > [SQLITE_OPEN_D
cb20: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
cb30: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
cb40: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a  EN_EXCLUSIVE].**
cb50: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
cb60: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
cb70: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
cb80: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
cb90: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
cba0: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
cbb0: 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b   closed.  ^The [
cbc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
cbd0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
cbe0: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
cbf0: 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64  MP databases and
cc00: 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c   their journals,
cc10: 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61   transient.** da
cc20: 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62  tabases, and sub
cc30: 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20  journals..**.** 
cc40: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
cc50: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
cc60: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
cc70: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
cc80: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
cc90: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
cca0: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
ccb0: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
ccc0: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
ccd0: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
cce0: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
ccf0: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
cd00: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
cd10: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
cd20: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
cd30: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
cd40: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
cd50: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
cd60: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
cd70: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
cd80: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
cd90: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
cda0: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
cdb0: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
cdc0: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
cdd0: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
cde0: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
cdf0: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
ce00: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
ce10: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  access..**.** ^A
ce20: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
ce30: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
ce40: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
ce50: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
ce60: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
ce70: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
ce80: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
ce90: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
cea0: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
ceb0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
cec0: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
ced0: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
cee0: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
cef0: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
cf00: 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a   in.  Note that.
cf10: 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  ** the xOpen met
cf20: 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65  hod must set the
cf30: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
cf40: 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72  ethods to either
cf50: 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c  .** a valid [sql
cf60: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
cf70: 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55   object or to NU
cf80: 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20  LL.  xOpen must 
cf90: 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20  do.** this even 
cfa0: 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c  if the open fail
cfb0: 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63  s.  SQLite expec
cfc0: 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69  ts that the sqli
cfd0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
cfe0: 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c  s.** element wil
cff0: 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72  l be valid after
d000: 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72   xOpen returns r
d010: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
d020: 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66   success.** or f
d030: 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f  ailure of the xO
d040: 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  pen call..**.** 
d050: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41  [[sqlite3_vfs.xA
d060: 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20  ccess]].** ^The 
d070: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
d080: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
d090: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
d0a0: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
d0b0: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
d0c0: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
d0d0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
d0e0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
d0f0: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
d100: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
d110: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
d120: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
d130: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
d140: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
d150: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
d160: 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65   readable.   The
d170: 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a   file can be a.*
d180: 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  * directory..**.
d190: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
d1a0: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
d1b0: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
d1c0: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
d1d0: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
d1e0: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
d1f0: 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73  me.  The exact s
d200: 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
d210: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61  t buffer.** is a
d220: 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20  lso passed as a 
d230: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74  parameter to bot
d240: 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74  h  methods. If t
d250: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
d260: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
d270: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
d280: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
d290: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
d2a0: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
d2b0: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
d2c0: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
d2d0: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
d2e0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
d2f0: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
d300: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
d310: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
d320: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
d330: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
d340: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
d350: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
d360: 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  ), xCurrentTime(
d370: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
d380: 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e  imeInt64().** in
d390: 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74  terfaces are not
d3a0: 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74   strictly a part
d3b0: 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74   of the filesyst
d3c0: 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65  em, but they are
d3d0: 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  .** included in 
d3e0: 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72  the VFS structur
d3f0: 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65  e for completene
d400: 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  ss..** The xRand
d410: 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f  omness() functio
d420: 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  n attempts to re
d430: 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65  turn nBytes byte
d440: 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61  s.** of good-qua
d450: 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20  lity randomness 
d460: 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20  into zOut.  The 
d470: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a  return value is.
d480: 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75  ** the actual nu
d490: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
d4a0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
d4b0: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c  ined..** The xSl
d4c0: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
d4d0: 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ses the calling 
d4e0: 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20  thread to sleep 
d4f0: 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20  for at.** least 
d500: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
d510: 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e  croseconds given
d520: 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  .  ^The xCurrent
d530: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
d540: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
d550: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
d560: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
d570: 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a  e and time as.**
d580: 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
d590: 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65  t value..** ^The
d5a0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
d5b0: 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  64() method retu
d5c0: 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67  rns, as an integ
d5d0: 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a  er, the Julian.*
d5e0: 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c  * Day Number mul
d5f0: 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30  tiplied by 86400
d600: 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20  000 (the number 
d610: 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
d620: 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72  in .** a 24-hour
d630: 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c   day).  .** ^SQL
d640: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
d650: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
d660: 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67  64() method to g
d670: 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  et the current.*
d680: 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  * date and time 
d690: 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69  if that method i
d6a0: 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20  s available (if 
d6b0: 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72  iVersion is 2 or
d6c0: 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64   .** greater and
d6d0: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
d6e0: 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
d6f0: 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c  L) and will fall
d700: 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72   back.** to xCur
d710: 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43  rentTime() if xC
d720: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
d730: 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  ) is unavailable
d740: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65  ..**.** ^The xSe
d750: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78  tSystemCall(), x
d760: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  GetSystemCall(),
d770: 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d   and xNestSystem
d780: 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  Call() interface
d790: 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65  s.** are not use
d7a0: 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20  d by the SQLite 
d7b0: 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74  core.  These opt
d7c0: 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ional interfaces
d7d0: 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a   are provided.**
d7e0: 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74   by some VFSes t
d7f0: 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73  o facilitate tes
d800: 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20  ting of the VFS 
d810: 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64  code. By overrid
d820: 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63  ing .** system c
d830: 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69  alls with functi
d840: 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f  ons under its co
d850: 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72  ntrol, a test pr
d860: 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d  ogram can.** sim
d870: 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64  ulate faults and
d880: 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e   error condition
d890: 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68  s that would oth
d8a0: 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63  erwise be diffic
d8b0: 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73  ult.** or imposs
d8c0: 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20  ible to induce. 
d8d0: 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74   The set of syst
d8e0: 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61  em calls that ca
d8f0: 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a  n be overridden.
d900: 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f  ** varies from o
d910: 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65  ne VFS to anothe
d920: 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20  r, and from one 
d930: 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73  version of the s
d940: 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a  ame VFS to the.*
d950: 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  * next.  Applica
d960: 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74  tions that use t
d970: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
d980: 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64  must be prepared
d990: 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61   for any.** or a
d9a0: 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ll of these inte
d9b0: 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c  rfaces to be NUL
d9c0: 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62  L or for their b
d9d0: 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67  ehavior to chang
d9e0: 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65  e.** from one re
d9f0: 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78  lease to the nex
da00: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
da10: 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70   must not attemp
da20: 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61  t to access.** a
da30: 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68  ny of these meth
da40: 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73  ods if the iVers
da50: 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69  ion of the VFS i
da60: 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a  s less than 3..*
da70: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
da80: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
da90: 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65  ite3_vfs;.typede
daa0: 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
dab0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f  _syscall_ptr)(vo
dac0: 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  id);.struct sqli
dad0: 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20  te3_vfs {.  int 
dae0: 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20  iVersion;       
daf0: 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72       /* Structur
db00: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
db10: 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a   (currently 3) *
db20: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
db30: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
db40: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
db50: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
db60: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
db70: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
db80: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
db90: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
dba0: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
dbb0: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
dbc0: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
dbd0: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
dbe0: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
dbf0: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
dc00: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
dc10: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
dc20: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
dc30: 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
dc40: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
dc50: 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
dc60: 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
dc70: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
dc80: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
dc90: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
dca0: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
dcb0: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
dcc0: 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
dcd0: 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
dce0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
dcf0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
dd00: 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
dd10: 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
dd20: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
dd30: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
dd40: 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  ags, int *pResOu
dd50: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
dd60: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
dd70: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
dd80: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
dd90: 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
dda0: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
ddb0: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
ddc0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ddd0: 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
dde0: 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
ddf0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
de00: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
de10: 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28  rrMsg);.  void (
de20: 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
de30: 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
de40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
de50: 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f  ol))(void);.  vo
de60: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
de70: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
de80: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
de90: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
dea0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
deb0: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
dec0: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
ded0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
dee0: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
def0: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
df00: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
df10: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
df20: 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
df30: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
df40: 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
df50: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
df60: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
df70: 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f  e in version 1 o
df80: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
df90: 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66   object.  ** def
dfa0: 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20  inition.  Those 
dfb0: 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20  that follow are 
dfc0: 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e  added in version
dfd0: 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f   2 or later.  */
dfe0: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
dff0: 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69  tTimeInt64)(sqli
e000: 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65  te3_vfs*, sqlite
e010: 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a  3_int64*);.  /*.
e020: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
e030: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
e040: 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f  rsions 1 and 2 o
e050: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
e060: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68   object..  ** Th
e070: 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f  ose below are fo
e080: 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20  r version 3 and 
e090: 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20  greater..  */.  
e0a0: 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d  int (*xSetSystem
e0b0: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
e0c0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e0d0: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73  zName, sqlite3_s
e0e0: 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73  yscall_ptr);.  s
e0f0: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
e100: 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43  tr (*xGetSystemC
e110: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
e120: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e130: 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63  Name);.  const c
e140: 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74  har *(*xNextSyst
e150: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e160: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e170: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20   *zName);.  /*. 
e180: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
e190: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
e1a0: 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20  sions 1 through 
e1b0: 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  3 of the sqlite_
e1c0: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
e1d0: 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20   New fields may 
e1e0: 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66  be appended in f
e1f0: 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20  igure versions. 
e200: 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20   The iVersion.  
e210: 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e  ** value will in
e220: 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72  crement whenever
e230: 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a   this happens. .
e240: 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43    */.};../*.** C
e250: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
e260: 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
e270: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
e280: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
e290: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
e2a0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
e2b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
e2c0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
e2d0: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
e2e0: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
e2f0: 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
e300: 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  ** what kind of 
e310: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
e320: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
e330: 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a  s looking for..*
e340: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
e350: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
e360: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e370: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
e380: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
e390: 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74  e exists..** Wit
e3a0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e3b0: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
e3c0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
e3d0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
e3e0: 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74  the named direct
e3f0: 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64  ory is both read
e400: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
e410: 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77  e.** (in other w
e420: 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63  ords, if files c
e430: 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d  an be added, rem
e440: 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65  oved, and rename
e450: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
e460: 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54  directory)..** T
e470: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
e480: 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74  _READWRITE const
e490: 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ant is currently
e4a0: 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68   used only by th
e4b0: 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65  e.** [temp_store
e4c0: 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
e4d0: 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20  a], though this 
e4e0: 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20  could change in 
e4f0: 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65  a future.** rele
e500: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
e510: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
e520: 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78  CESS_READ, the x
e530: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
e540: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
e550: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
e560: 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54  able.  The SQLIT
e570: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f  E_ACCESS_READ co
e580: 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72  nstant is.** cur
e590: 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74  rently unused, t
e5a0: 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62  hough it might b
e5b0: 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75  e used in a futu
e5c0: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
e5d0: 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
e5e0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
e5f0: 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64  S_EXISTS    0.#d
e600: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
e610: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20  ESS_READWRITE 1 
e620: 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41    /* Used by PRA
e630: 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64  GMA temp_store_d
e640: 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66  irectory */.#def
e650: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
e660: 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20  S_READ      2   
e670: 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a  /* Unused */../*
e680: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
e690: 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d  ags for the xShm
e6a0: 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a  Lock VFS method.
e6b0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
e6c0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ger constants de
e6d0: 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73  fine the various
e6e0: 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69   locking operati
e6f0: 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62  ons.** allowed b
e700: 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  y the xShmLock m
e710: 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65  ethod of [sqlite
e720: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20  3_io_methods].  
e730: 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  The.** following
e740: 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65   are the only le
e750: 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  gal combinations
e760: 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65   of flags to the
e770: 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  .** xShmLock met
e780: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
e790: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
e7a0: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
e7b0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
e7c0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
e7d0: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
e7e0: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
e7f0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
e800: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
e810: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
e820: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
e830: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
e840: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
e850: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65   </ul>.**.** Whe
e860: 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65  n unlocking, the
e870: 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20   same SHARED or 
e880: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d  EXCLUSIVE flag m
e890: 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20  ust be supplied 
e8a0: 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20  as.** was given 
e8b0: 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  on the correspon
e8c0: 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a  ding lock.  .**.
e8d0: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
e8e0: 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73  method can trans
e8f0: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e  ition between un
e900: 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45  locked and SHARE
e910: 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20  D or.** between 
e920: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43  unlocked and EXC
e930: 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e  LUSIVE.  It cann
e940: 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  ot transition be
e950: 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20  tween SHARED.** 
e960: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a  and EXCLUSIVE..*
e970: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e980: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  _SHM_UNLOCK     
e990: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
e9a0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20  TE_SHM_LOCK     
e9b0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
e9c0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20  LITE_SHM_SHARED 
e9d0: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
e9e0: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
e9f0: 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a  SIVE    8../*.**
ea00: 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d   CAPI3REF: Maxim
ea10: 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65  um xShmLock inde
ea20: 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d  x.**.** The xShm
ea30: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b  Lock method on [
ea40: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
ea50: 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75  ds] may use valu
ea60: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  es.** between 0 
ea70: 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62  and this upper b
ea80: 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66  ound as its "off
ea90: 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  set" argument..*
eaa0: 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
eab0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74  e will never att
eac0: 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20  empt to acquire 
ead0: 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20  or release a.** 
eae0: 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20  lock outside of 
eaf0: 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64  this range.*/.#d
eb00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
eb10: 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a  _NLOCK        8.
eb20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
eb30: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
eb40: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
eb50: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
eb60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
eb70: 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69  routine initiali
eb80: 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74  zes the.** SQLit
eb90: 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65  e library.  ^The
eba0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
ebb0: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
ebc0: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
ebd0: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
ebe0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
ebf0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ec00: 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ze()..** These r
ec10: 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69  outines are desi
ec20: 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70  gned to aid in p
ec30: 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
ec40: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75  ation and.** shu
ec50: 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65  tdown on embedde
ec60: 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b  d systems.  Work
ec70: 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74  station applicat
ec80: 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51  ions using.** SQ
ec90: 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f  Lite normally do
eca0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76   not need to inv
ecb0: 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68  oke either of th
ecc0: 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
ecd0: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
ece0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ecf0: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
ed00: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
ed10: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
ed20: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
ed30: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
ed40: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
ed50: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
ed60: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
ed70: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
ed80: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
ed90: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
eda0: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
edb0: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
edc0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
edd0: 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66  .  ^(Only an eff
ede0: 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f  ective call.** o
edf0: 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
ee00: 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20  lize() does any 
ee10: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20  initialization. 
ee20: 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73   All other calls
ee30: 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73  .** are harmless
ee40: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
ee50: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
ee60: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73  e3_shutdown() is
ee70: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
ee80: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68  call if it is th
ee90: 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20  e first.** call 
eea0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
eeb0: 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20  own() since the 
eec0: 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  last sqlite3_ini
eed0: 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e  tialize().  ^(On
eee0: 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69  ly.** an effecti
eef0: 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ve call to sqlit
ef00: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f  e3_shutdown() do
ef10: 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c  es any deinitial
ef20: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20  ization..** All 
ef30: 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c  other valid call
ef40: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  s to sqlite3_shu
ef50: 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d  tdown() are harm
ef60: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
ef70: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
ef80: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e  _initialize() in
ef90: 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61  terface is threa
efa0: 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74  dsafe, but sqlit
efb0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
efc0: 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71   is not.  The sq
efd0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
efe0: 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20   interface must 
eff0: 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66  only be called f
f000: 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20  rom a.** single 
f010: 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65  thread.  All ope
f020: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
f030: 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65  ections] must be
f040: 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a   closed and all.
f050: 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ** other SQLite 
f060: 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62  resources must b
f070: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72  e deallocated pr
f080: 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a  ior to invoking.
f090: 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ** sqlite3_shutd
f0a0: 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  own()..**.** Amo
f0b0: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
f0c0: 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   ^sqlite3_initia
f0d0: 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f  lize() will invo
f0e0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
f0f0: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
f100: 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68  rly, ^sqlite3_sh
f110: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c  utdown().** will
f120: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
f130: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
f140: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
f150: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
f160: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
f170: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
f180: 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d  ..** ^If for som
f190: 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65  e reason, sqlite
f1a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f1b0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74  s unable to init
f1c0: 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69  ialize.** the li
f1d0: 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69  brary (perhaps i
f1e0: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  t is unable to a
f1f0: 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64  llocate a needed
f200: 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a   resource such.*
f210: 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74  * as a mutex) it
f220: 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72   returns an [err
f230: 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74  or code] other t
f240: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  han [SQLITE_OK].
f250: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
f260: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f270: 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
f280: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
f290: 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53   many other.** S
f2a0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
f2b0: 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c   so that an appl
f2c0: 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20  ication usually 
f2d0: 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
f2e0: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
f2f0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f300: 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65  directly.  For e
f310: 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33  xample, [sqlite3
f320: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c  _open()].** call
f330: 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
f340: 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51  lize() so the SQ
f350: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
f360: 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
f370: 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65  ly.** initialize
f380: 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
f390: 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65  open()] is calle
f3a0: 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20  d if it has not 
f3b0: 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a  be initialized.*
f3c0: 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77  * already.  ^How
f3d0: 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
f3e0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
f3f0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   the [SQLITE_OMI
f400: 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63  T_AUTOINIT].** c
f410: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
f420: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74  on, then the aut
f430: 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20  omatic calls to 
f440: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f450: 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74  ze().** are omit
f460: 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  ted and the appl
f470: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c  ication must cal
f480: 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  l sqlite3_initia
f490: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a  lize() directly.
f4a0: 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ** prior to usin
f4b0: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
f4c0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
f4d0: 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61  or maximum porta
f4e0: 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73  bility,.** it is
f4f0: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
f500: 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  t applications a
f510: 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c  lways invoke sql
f520: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f530: 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72  ).** directly pr
f540: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
f550: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
f560: 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65  terface.  Future
f570: 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20   releases.** of 
f580: 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69  SQLite may requi
f590: 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68  re this.  In oth
f5a0: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65  er words, the be
f5b0: 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64  havior exhibited
f5c0: 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
f5d0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
f5e0: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
f5f0: 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65  TOINIT] might be
f600: 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
f610: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
f620: 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
f630: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
f640: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
f650: 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
f660: 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
f670: 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
f680: 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
f690: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
f6a0: 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
f6b0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f6c0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
f6d0: 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
f6e0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f6f0: 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
f700: 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
f710: 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
f720: 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
f730: 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
f740: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
f750: 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
f760: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
f770: 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
f780: 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
f790: 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
f7a0: 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
f7b0: 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
f7c0: 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
f7d0: 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
f7e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f7f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
f800: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
f810: 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
f820: 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
f830: 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
f840: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
f850: 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
f860: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
f870: 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
f880: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f890: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
f8a0: 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
f8b0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f8c0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
f8d0: 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
f8e0: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
f8f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
f900: 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
f910: 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
f920: 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
f930: 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
f940: 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
f950: 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
f960: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
f970: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f980: 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
f990: 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
f9a0: 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
f9b0: 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73  or Unix, Windows
f9c0: 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68  , or OS/2..** Wh
f9d0: 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64  en [custom build
f9e0: 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74  s | built for ot
f9f0: 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a  her platforms].*
fa00: 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51  * (using the [SQ
fa10: 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d  LITE_OS_OTHER=1]
fa20: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
fa30: 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70   option) the app
fa40: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
fa50: 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20  pply a suitable 
fa60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
fa70: 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  or.** sqlite3_os
fa80: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
fa90: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41  te3_os_end().  A
faa0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  n application-su
fab0: 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d  pplied.** implem
fac0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
fad0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72  te3_os_init() or
fae0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
faf0: 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e  ).** must return
fb00: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
fb10: 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65  success and some
fb20: 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f   other [error co
fb30: 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c  de] upon.** fail
fb40: 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ure..*/.int sqli
fb50: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76  te3_initialize(v
fb60: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
fb70: 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
fb80: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
fb90: 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74  _init(void);.int
fba0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
fbb0: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
fbc0: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
fbd0: 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
fbe0: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
fbf0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
fc00: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
fc10: 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
fc20: 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
fc30: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
fc40: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
fc50: 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
fc60: 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
fc70: 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
fc80: 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
fc90: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
fca0: 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
fcb0: 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
fcc0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
fcd0: 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
fce0: 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
fcf0: 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
fd00: 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
fd10: 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
fd20: 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
fd30: 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
fd40: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fd50: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
fd60: 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
fd70: 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
fd80: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
fd90: 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
fda0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
fdb0: 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
fdc0: 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
fdd0: 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
fde0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
fdf0: 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
fe00: 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
fe10: 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
fe20: 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
fe30: 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
fe40: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
fe50: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
fe60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
fe70: 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
fe80: 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
fe90: 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
fea0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
feb0: 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
fec0: 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
fed0: 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
fee0: 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
fef0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
ff00: 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
ff10: 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
ff20: 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
ff30: 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
ff40: 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
ff50: 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
ff60: 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
ff70: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
ff80: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
ff90: 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
ffa0: 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
ffb0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ffc0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
ffd0: 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
ffe0: 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
fff0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
10000 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
10010 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
10020 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
10030 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
10040 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
10050 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
10060 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
10070 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10080 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
10090 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
100a0 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
100b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
100c0 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
100d0 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
100e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
100f0 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
10100 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
10110 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
10120 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
10130 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
10140 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
10150 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
10160 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  code]..*/.int sq
10170 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
10180 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
10190 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
101a0 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
101b0 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  ections.**.** Th
101c0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
101d0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
101e0 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
101f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
10200 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
10210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10220 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
10230 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
10240 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10250 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
10260 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
10270 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
10280 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
10290 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
102a0 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
102b0 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
102c0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
102d0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
102e0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
102f0 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
10300 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
10310 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
10320 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
10330 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
10340 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
10350 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
10360 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
10370 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10380 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
10390 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
103a0 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
103b0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
103c0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
103d0 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
103e0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
103f0 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
10400 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
10410 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
10420 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
10430 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
10440 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10450 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
10460 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
10470 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10480 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
10490 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
104a0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
104b0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
104c0 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
104d0 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
104e0 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
104f0 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
10500 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
10510 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
10520 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
10530 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
10540 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
10550 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
10560 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
10570 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10580 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
10590 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
105a0 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
105b0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
105c0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
105d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
105e0 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
105f0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
10600 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
10610 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
10620 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
10630 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
10640 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
10650 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
10660 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
10670 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
10680 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
10690 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
106a0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
106b0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
106c0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
106d0 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
106e0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
106f0 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
10700 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
10710 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
10720 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
10730 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
10740 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
10750 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
10760 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
10770 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
10780 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
10790 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
107a0 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
107b0 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
107c0 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
107d0 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
107e0 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
107f0 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
10800 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
10810 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
10820 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
10830 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
10840 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
10850 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
10860 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
10870 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
10880 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
10890 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
108a0 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
108b0 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
108c0 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
108d0 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
108e0 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
108f0 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
10900 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
10910 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
10920 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
10930 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
10940 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
10950 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
10960 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
10970 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
10980 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
10990 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
109a0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
109b0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
109c0 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
109d0 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
109e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
109f0 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
10a00 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
10a10 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
10a20 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
10a30 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
10a40 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
10a50 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
10a60 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
10a70 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
10a80 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
10a90 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
10aa0 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
10ab0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
10ac0 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
10ad0 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
10ae0 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
10af0 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
10b00 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
10b10 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
10b20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10b30 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
10b40 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
10b50 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
10b60 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
10b70 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
10b80 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
10b90 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
10ba0 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
10bb0 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
10bc0 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
10bd0 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
10be0 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
10bf0 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
10c00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10c10 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
10c20 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
10c30 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
10c40 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
10c50 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
10c60 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
10c70 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
10c80 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
10c90 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
10ca0 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
10cb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
10cc0 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
10cd0 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
10ce0 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
10cf0 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f  y allocator.  Fo
10d00 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
10d10 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
10d20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
10d30 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
10d40 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
10d50 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
10d60 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
10d70 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
10d80 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
10d90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
10da0 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
10db0 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
10dc0 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
10dd0 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
10de0 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
10df0 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
10e00 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
10e10 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
10e20 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
10e30 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
10e40 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
10e50 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
10e60 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
10e70 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
10e80 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
10e90 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
10ea0 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
10eb0 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
10ec0 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
10ed0 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
10ee0 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
10ef0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
10f00 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
10f10 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
10f20 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
10f30 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
10f40 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
10f50 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
10f60 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
10f70 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
10f80 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
10f90 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
10fa0 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
10fb0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
10fc0 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
10fd0 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
10fe0 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
10ff0 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
11000 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
11010 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
11020 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
11030 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
11040 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
11050 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
11060 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
11070 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
11080 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
11090 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
110a0 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
110b0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
110c0 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
110d0 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
110e0 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
110f0 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
11100 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
11110 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
11120 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
11130 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
11140 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11150 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
11160 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
11170 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
11180 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
11190 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
111a0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
111b0 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
111c0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
111d0 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
111e0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
111f0 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
11200 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
11210 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
11220 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
11230 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
11240 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
11250 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
11260 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
11270 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
11280 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
11290 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
112a0 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
112b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
112c0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
112d0 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
112e0 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
112f0 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
11300 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
11310 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
11320 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
11330 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
11340 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11350 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
11360 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
11370 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
11380 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
11390 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
113a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
113b0 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
113c0 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57   Options.** KEYW
113d0 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61  ORDS: {configura
113e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a  tion option}.**.
113f0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
11400 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
11410 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
11420 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11430 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
11440 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
11450 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
11460 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
11470 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
11480 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
11490 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
114a0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
114b0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
114c0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
114d0 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
114e0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
114f0 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
11500 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
11510 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
11520 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
11530 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
11540 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
11550 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
11560 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
11570 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
11580 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
11590 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
115a0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
115b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
115c0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
115d0 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
115e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
115f0 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
11600 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
11610 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11620 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c  SINGLETHREAD]] <
11630 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11640 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
11650 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
11660 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
11670 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
11680 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
11690 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
116a0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
116b0 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
116c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
116d0 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
116e0 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
116f0 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
11700 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
11710 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
11720 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
11730 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
11740 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11750 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11760 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11770 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11780 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11790 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
117a0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
117b0 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
117c0 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
117d0 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
117e0 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
117f0 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
11800 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
11810 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
11820 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
11830 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
11840 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
11850 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11860 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
11870 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
11880 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11890 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
118a0 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
118b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
118c0 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
118d0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
118e0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
118f0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
11900 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
11910 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
11920 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
11930 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
11940 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
11950 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
11960 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
11970 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
11980 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
11990 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
119a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
119b0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
119c0 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
119d0 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
119e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
119f0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11a00 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
11a10 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
11a20 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
11a30 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
11a40 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
11a50 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
11a60 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
11a70 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
11a80 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
11a90 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
11aa0 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
11ab0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
11ac0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
11ad0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
11ae0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
11af0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
11b00 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
11b10 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
11b20 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11b30 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
11b40 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
11b50 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
11b60 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
11b70 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
11b80 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11b90 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
11ba0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
11bb0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
11bc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
11bd0 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
11be0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
11bf0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11c00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
11c10 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c  ALIZED]] <dt>SQL
11c20 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
11c30 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
11c40 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
11c50 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
11c60 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
11c70 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
11c80 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
11c90 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
11ca0 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
11cb0 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
11cc0 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
11cd0 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
11ce0 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
11cf0 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
11d00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11d10 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
11d20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
11d30 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
11d40 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
11d50 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
11d60 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11d70 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
11d80 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
11d90 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
11da0 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
11db0 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
11dc0 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
11dd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
11de0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
11df0 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
11e00 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
11e10 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
11e20 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
11e30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11e40 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
11e50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11e60 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
11e70 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
11e80 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
11e90 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11ea0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11eb0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11ec0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11ed0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11ee0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11ef0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
11f00 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
11f10 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
11f20 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11f30 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
11f40 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11f50 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11f60 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
11f70 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
11f80 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
11f90 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
11fa0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11fb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11fc0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20  CONFIG_MALLOC]] 
11fd0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11fe0 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
11ff0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
12000 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12010 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12020 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12030 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
12040 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
12050 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
12060 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12070 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
12080 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
12090 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
120a0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
120b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
120c0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
120d0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
120e0 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
120f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12100 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
12110 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
12120 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
12130 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
12140 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
12150 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12160 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12170 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
12180 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
12190 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
121a0 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
121b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
121c0 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
121d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
121e0 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
121f0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
12200 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12210 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
12220 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12230 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
12240 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12250 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12260 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12270 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
12280 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  * The [sqlite3_m
12290 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
122a0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
122b0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
122c0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
122d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
122e0 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
122f0 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
12300 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
12310 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
12320 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12330 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
12340 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
12350 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
12360 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
12370 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
12380 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
12390 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
123a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
123b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
123c0 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATUS]] <dt>SQLIT
123d0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
123e0 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
123f0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
12400 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74  IG_MEMSTATUS opt
12410 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
12420 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
12430 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70  e int,.** interp
12440 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
12450 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
12460 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
12470 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a  e collection of.
12480 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
12490 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e  tion statistics.
124a0 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
124b0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
124c0 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  tics are.** disa
124d0 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  bled, the follow
124e0 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
124f0 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
12500 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
12510 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
12520 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12530 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
12540 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
12550 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
12560 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
12570 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
12580 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
12590 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
125a0 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  us()].**   </ul>
125b0 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
125c0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
125d0 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
125e0 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
125f0 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
12600 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
12610 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
12620 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
12630 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
12640 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
12650 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
12660 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
12670 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
12680 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12690 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51  SCRATCH]] <dt>SQ
126a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
126b0 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
126c0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
126d0 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69  FIG_SCRATCH opti
126e0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
126f0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
12700 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  fer.** that SQLi
12710 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73  te can use for s
12720 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
12730 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65  ^(There are thre
12740 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74  e arguments.** t
12750 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
12760 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e  SCRATCH:  A poin
12770 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
12780 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
12790 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
127a0 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
127b0 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
127c0 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
127d0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
127e0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
127f0 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
12800 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
12810 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
12820 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a  ations (N).)^.**
12830 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12840 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
12850 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
12860 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
12870 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
12880 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
12890 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
128a0 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d  e will not use m
128b0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72  ore than one scr
128c0 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
128d0 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c   thread..** ^SQL
128e0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72  ite will never r
128f0 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68  equest a scratch
12900 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20   buffer that is 
12910 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74  more than 6.** t
12920 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
12930 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20  e page size..** 
12940 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
12950 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
12960 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
12970 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
12980 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
12990 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
129a0 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
129b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
129c0 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
129d0 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
129e0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
129f0 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  p>.** ^When the 
12a00 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76  application prov
12a10 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20  ides any amount 
12a20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  of scratch memor
12a30 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54  y using.** SQLIT
12a40 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
12a50 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20  , SQLite avoids 
12a60 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67  unnecessary larg
12a70 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
12a80 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61  lloc|heap alloca
12a90 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20  tions]..** This 
12aa0 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e  can help [Robson
12ab0 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d   proof|prevent m
12ac0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12ad0 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74   failures] due t
12ae0 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65  o heap.** fragme
12af0 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d  ntation in low-m
12b00 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73  emory embedded s
12b10 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  ystems..** </dd>
12b20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12b30 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
12b40 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12b50 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
12b60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
12b70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
12b80 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20  AGECACHE option 
12b90 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
12ba0 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
12bb0 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
12bc0 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20  can use for the 
12bd0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
12be0 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
12bf0 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63  ault page.** cac
12c00 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
12c10 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
12c20 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
12c30 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
12c40 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
12c50 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
12c60 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
12c70 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
12c80 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
12c90 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 0a  CONFIG_PCACHE2].
12ca0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
12cb0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65   option..** ^The
12cc0 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
12cd0 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
12ce0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
12cf0 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a  E: A pointer to.
12d00 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  ** 8-byte aligne
12d10 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  d.** memory, the
12d20 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
12d30 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
12d40 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
12d50 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
12d60 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
12d70 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
12d80 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
12d90 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
12da0 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
12db0 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
12dc0 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73  nd 65536) plus s
12dd0 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20  ome extra bytes 
12de0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
12df0 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e   header.  ^The n
12e00 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62  umber of extra b
12e10 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74  ytes needed by t
12e20 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a  he page header.*
12e30 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
12e40 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53  ned using the [S
12e50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
12e60 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f  CHE_HDRSZ] optio
12e70 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  n .** to [sqlite
12e80 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20  3_config()]..** 
12e90 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
12ea0 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
12eb0 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
12ec0 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72  * for the sz par
12ed0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72  ameter to be lar
12ee0 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61  ger than necessa
12ef0 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ry.  The first.*
12f00 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
12f10 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  d pointer to an 
12f20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
12f30 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74  lock of memory t
12f40 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61  hat.** is at lea
12f50 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
12f60 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69   memory, otherwi
12f70 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  se subsequent be
12f80 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
12f90 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69  efined..** ^SQLi
12fa0 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
12fb0 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
12fc0 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
12fd0 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
12fe0 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
12ff0 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
13000 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
13010 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
13020 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
13030 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
13040 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
13050 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
13060 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
13070 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
13080 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
13090 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
130a0 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
130b0 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
130c0 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ace.</dd>.**.** 
130d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
130e0 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
130f0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
13100 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
13110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
13120 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  AP option specif
13130 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
13140 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74  ory buffer .** t
13150 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
13160 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
13170 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
13180 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
13190 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f  ds.** beyond tho
131a0 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  se provided for 
131b0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
131c0 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a  G_SCRATCH] and.*
131d0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
131e0 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
131f0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
13200 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69  IG_HEAP option i
13210 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
13220 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
13230 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65  mpiled.** with e
13240 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
13250 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
13260 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
13270 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74  MEMSYS5] and ret
13280 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
13290 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65  ERROR] if invoke
132a0 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20  d otherwise..** 
132b0 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
132c0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
132d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
132e0 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61  :.** An 8-byte a
132f0 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
13300 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
13310 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
13320 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
13330 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
13340 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
13350 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
13360 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
13370 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
13380 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
13390 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
133a0 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
133b0 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
133c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
133d0 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
133e0 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
133f0 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
13400 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
13410 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
13420 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
13430 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
13440 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
13450 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  ot NULL then the
13460 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
13470 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
13480 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
13490 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
134a0 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
134b0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
134c0 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
134d0 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
134e0 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
134f0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
13500 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
13510 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
13520 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
13530 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
13540 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
13550 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13560 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
13570 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
13580 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
13590 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
135a0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
135b0 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
135c0 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
135d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
135e0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
135f0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
13600 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13610 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13620 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
13630 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13640 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a  ment which is a.
13650 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
13660 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13670 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13680 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13690 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
136a0 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c  ent specifies al
136b0 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
136c0 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
136d0 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a  es to be used.**
136e0 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75   in place the mu
136f0 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
13700 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
13710 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
13720 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
13730 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
13740 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13750 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13760 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
13770 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
13780 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
13790 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
137a0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
137b0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
137c0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
137d0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
137e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
137f0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
13800 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
13810 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
13820 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
13830 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
13840 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
13850 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13860 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
13870 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
13880 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13890 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
138a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
138b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
138c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
138d0 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
138e0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
138f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13900 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13910 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f  G_GETMUTEX optio
13920 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13930 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
13940 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
13950 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
13960 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13970 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
13980 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
13990 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
139a0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
139b0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
139c0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
139d0 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
139e0 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
139f0 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
13a00 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
13a10 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
13a20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
13a30 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
13a40 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
13a50 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
13a60 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
13a70 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
13a80 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
13a90 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
13aa0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13ab0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
13ac0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13ad0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
13ae0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
13af0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
13b00 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
13b10 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
13b20 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
13b30 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
13b40 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
13b50 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
13b60 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
13b70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13b80 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
13b90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
13ba0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
13bb0 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
13bc0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13bd0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13be0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13bf0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
13c00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13c10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13c20 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e  LOOKASIDE option
13c30 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
13c40 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
13c50 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75  ine.** the defau
13c60 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61  lt size of looka
13c70 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65  side memory on e
13c80 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ach [database co
13c90 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
13ca0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13cb0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
13cc0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
13cd0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
13ce0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
13cf0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
13d00 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
13d10 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
13d20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
13d30 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   ^(SQLITE_CONFIG
13d40 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65  _LOOKASIDE.** se
13d50 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c  ts the <i>defaul
13d60 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
13d70 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
13d80 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
13d90 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20  SIDE].** option 
13da0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
13db0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
13dc0 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
13dd0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
13de0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
13df0 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
13e00 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
13e10 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13e20 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
13e30 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13e40 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
13e50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
13e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13e70 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
13e80 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13e90 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
13ea0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13eb0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
13ec0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
13ed0 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
13ee0 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
13ef0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63  interface to a c
13f00 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
13f10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
13f20 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61  )^.** ^SQLite ma
13f30 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
13f40 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  e [sqlite3_pcach
13f50 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
13f60 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ct.</dd>.**.** [
13f70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
13f80 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
13f90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13fa0 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
13fb0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
13fc0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
13fd0 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
13fe0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13ff0 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
14000 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14010 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
14020 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
14030 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
14040 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65   of.** the curre
14050 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  nt page cache im
14060 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
14070 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
14080 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14090 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
140a0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
140b0 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
140c0 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
140d0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
140e0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
140f0 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
14100 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
14110 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
14120 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14130 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
14140 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
14150 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
14160 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
14170 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
14180 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
14190 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
141a0 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
141b0 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
141c0 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
141d0 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
141e0 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
141f0 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
14200 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
14210 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
14220 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
14230 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
14240 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
14250 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
14260 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
14270 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
14280 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
14290 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
142a0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
142b0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
142c0 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
142d0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
142e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
142f0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
14300 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
14310 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
14320 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
14330 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
14340 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
14350 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
14360 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
14370 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
14380 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
14390 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
143a0 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
143b0 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
143c0 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
143d0 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
143e0 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
143f0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
14400 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
14410 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
14420 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
14430 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
14440 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
14450 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
14460 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
14470 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
14480 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
14490 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
144a0 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
144b0 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
144c0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
144d0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
144e0 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
144f0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
14500 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
14510 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
14520 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
14530 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
14540 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
14550 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
14560 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14570 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
14580 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14590 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68  _URI.** <dd>^(Th
145a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
145b0 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  URI option takes
145c0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
145d0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a  nt of type int..
145e0 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  ** If non-zero, 
145f0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
14600 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
14610 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
14620 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
14630 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e  .** then URI han
14640 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
14650 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49  y disabled.)^ ^I
14660 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
14670 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e  s globally.** en
14680 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
14690 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b  ames passed to [
146a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
146b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
146c0 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
146d0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
146e0 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
146f0 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
14700 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
14710 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
14720 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
14730 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
14740 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
14750 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
14760 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
14770 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
14780 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14790 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
147a0 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
147b0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
147c0 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
147d0 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
147e0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
147f0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
14800 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
14810 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
14820 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
14830 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
14840 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
14850 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
14860 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
14870 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
14880 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
14890 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
148a0 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
148b0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
148c0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
148d0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
148e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
148f0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
14900 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
14910 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14920 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
14930 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SCAN option take
14940 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
14950 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77  er.** argument w
14960 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
14970 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
14980 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
14990 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a  ble or disable.*
149a0 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  * the use of cov
149b0 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
149c0 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
149d0 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
149e0 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54  optimizer..** ^T
149f0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
14a00 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
14a10 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
14a20 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
14a30 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
14a40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14a50 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
14a60 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
14a70 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
14a80 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
14a90 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
14aa0 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
14ab0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
14ac0 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
14ad0 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
14ae0 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
14af0 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
14b00 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
14b10 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
14b20 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  * when the optim
14b30 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
14b40 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
14b50 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
14b60 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
14b70 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
14b80 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
14b90 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
14ba0 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
14bb0 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
14bc0 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
14bd0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
14be0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14bf0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
14c00 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14c10 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
14c20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14c30 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
14c40 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14c50 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
14c60 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
14c70 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
14c80 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
14c90 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
14ca0 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
14cb0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
14cc0 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
14cd0 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
14ce0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
14cf0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
14d00 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
14d10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
14d20 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
14d30 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
14d40 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
14d50 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14d60 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
14d70 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
14d80 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
14d90 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
14da0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14db0 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
14dc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
14dd0 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
14de0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
14df0 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
14e00 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
14e10 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
14e20 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
14e30 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
14e40 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
14e50 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
14e60 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
14e70 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
14e80 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
14e90 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
14ea0 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
14eb0 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
14ec0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
14ed0 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
14ee0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14ef0 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
14f00 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
14f10 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
14f20 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
14f30 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
14f40 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
14f50 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
14f60 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
14f70 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
14f80 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
14f90 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
14fa0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
14fb0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
14fc0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
14fd0 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
14fe0 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
14ff0 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
15000 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
15010 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
15020 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
15030 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
15040 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
15050 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
15060 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
15070 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
15080 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
15090 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
150a0 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
150b0 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
150c0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
150d0 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
150e0 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
150f0 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
15100 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
15110 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
15120 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
15130 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
15140 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
15150 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15160 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
15170 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  >^SQLITE_CONFIG_
15180 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
15190 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
151a0 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
151b0 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
151c0 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
151d0 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
151e0 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
151f0 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
15200 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
15210 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
15220 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
15230 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  ize limit..** ^T
15240 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
15250 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  ng can be overri
15260 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74  dden by each dat
15270 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15280 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72   using.** either
15290 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61   the [PRAGMA mma
152a0 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c  p_size] command,
152b0 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65   or by using the
152c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
152d0 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
152e0 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68  e control.  ^(Th
152f0 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
15300 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77  d mmap size.** w
15310 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20  ill be silently 
15320 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63  truncated if nec
15330 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69  essary so that i
15340 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65  t does not excee
15350 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d the.** compile
15360 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
15370 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
15380 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
15390 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
153a0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
153b0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
153c0 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
153d0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
153e0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
153f0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
15400 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
15410 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
15420 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ult..**.** [[SQL
15430 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15440 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  _HEAPSIZE]].** <
15450 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15460 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a  _WIN32_HEAPSIZE.
15470 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15480 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15490 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20  HEAPSIZE option 
154a0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
154b0 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a  e if SQLite is.*
154c0 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57  * compiled for W
154d0 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20  indows with the 
154e0 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41  [SQLITE_WIN32_MA
154f0 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOC] pre-proces
15500 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66  sor macro.** def
15510 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f  ined. ^SQLITE_CO
15520 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15530 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62  IZE takes a 32-b
15540 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
15550 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61  ger value.** tha
15560 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
15570 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
15580 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70  the created heap
15590 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ..** </dl>.**.**
155a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
155b0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a  _PCACHE_HDRSZ]].
155c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
155d0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
155e0 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
155f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15600 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20  HE_HDRSZ option 
15610 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
15620 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
15630 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
15640 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
15650 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61   writes into tha
15660 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75  t integer the nu
15670 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a  mber of extra.**
15680 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20   bytes per page 
15690 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63  required for eac
156a0 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54  h page in [SQLIT
156b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
156c0 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75  HE]..** The amou
156d0 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63  nt of extra spac
156e0 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63  e required can c
156f0 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20  hange depending 
15700 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c  on the compiler,
15710 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66  .** target platf
15720 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20  orm, and SQLite 
15730 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  version..**.** [
15740 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
15750 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  MASZ]].** <dt>SQ
15760 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
15770 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
15780 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
15790 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
157a0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
157b0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e  r which.** is an
157c0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
157d0 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22  r and sets the "
157e0 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  Minimum PMA Size
157f0 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74  " for the multit
15800 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65  hreaded.** sorte
15810 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  r to that intege
15820 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  r.  The default 
15830 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  minimum PMA Size
15840 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a   is set by the.*
15850 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52  * [SQLITE_SORTER
15860 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d  _PMASZ] compile-
15870 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65  time option.  Ne
15880 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61  w threads are la
15890 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c  unched.** to hel
158a0 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72  p with sort oper
158b0 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74  ations when mult
158c0 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e  ithreaded sortin
158d0 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20  g.** is enabled 
158e0 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47  (using the [PRAG
158f0 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d  MA threads] comm
15900 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f  and) and the amo
15910 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a  unt of content.*
15920 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65  * to be sorted e
15930 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20  xceeds the page 
15940 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d  size times the m
15950 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a  inimum of the.**
15960 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73   [PRAGMA cache_s
15970 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64  ize] setting and
15980 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 20   this value..** 
15990 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
159a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
159b0 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
159c0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
159d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
159e0 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
159f0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
15a00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15a10 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
15a20 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
15a30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15a40 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
15a50 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
15a60 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
15a70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15a80 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
15a90 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
15aa0 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
15ab0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15ac0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
15ad0 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
15ae0 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
15af0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15b00 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
15b10 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
15b20 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
15b30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15b40 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
15b50 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
15b60 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
15b70 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
15b80 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15b90 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
15ba0 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
15bb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15bc0 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
15bd0 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
15be0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
15bf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15c00 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
15c10 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
15c20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
15c30 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
15c40 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
15c50 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
15c60 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
15c70 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
15c80 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15c90 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
15ca0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
15cb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15cc0 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
15cd0 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
15ce0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15cf0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15d00 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
15d10 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
15d20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
15d30 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
15d40 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
15d50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15d60 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
15d70 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
15d80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15d90 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
15da0 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
15db0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
15dc0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
15dd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15de0 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
15df0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
15e00 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
15e10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15e20 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
15e30 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e  X_SCAN 20  /* in
15e40 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
15e50 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
15e60 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78  G       21  /* x
15e70 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f  Sqllog, void* */
15e80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15e90 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
15ea0 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74      22  /* sqlit
15eb0 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65  e3_int64, sqlite
15ec0 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69  3_int64 */.#defi
15ed0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15ee0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
15ef0 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20       23  /* int 
15f00 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
15f10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15f20 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20  CACHE_HDRSZ     
15f30 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70     24  /* int *p
15f40 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  sz */.#define SQ
15f50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
15f60 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Z               
15f70 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20  25  /* unsigned 
15f80 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a  int szPma */../*
15f90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
15fa0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
15fb0 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
15fc0 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
15fd0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
15fe0 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
15ff0 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
16000 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
16010 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
16020 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
16030 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
16040 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
16050 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
16060 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
16070 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16080 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
16090 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
160a0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
160b0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
160c0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
160d0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
160e0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
160f0 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
16100 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
16110 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
16120 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
16130 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
16140 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
16150 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
16160 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
16170 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
16180 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
16190 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
161a0 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
161b0 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
161c0 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
161d0 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
161e0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
161f0 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
16200 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
16210 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
16220 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
16230 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
16240 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
16250 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
16260 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
16270 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
16280 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
16290 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
162a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
162b0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
162c0 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
162d0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
162e0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
162f0 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
16300 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
16310 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
16320 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
16330 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
16340 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
16350 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
16360 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
16370 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
16380 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
16390 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
163a0 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
163b0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
163c0 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
163d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
163e0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
163f0 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
16400 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
16410 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
16420 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
16430 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
16440 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
16450 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
16460 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
16470 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16480 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
16490 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
164a0 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
164b0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
164c0 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
164d0 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
164e0 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
164f0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
16500 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
16510 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16520 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
16530 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
16540 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
16550 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
16560 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
16570 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
16580 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
16590 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
165a0 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
165b0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
165c0 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
165d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
165e0 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
165f0 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
16600 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
16610 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
16620 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
16630 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
16640 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
16650 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
16660 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
16670 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
16680 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
16690 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
166a0 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
166b0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
166c0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
166d0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
166e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
166f0 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
16700 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
16710 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
16720 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
16730 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
16740 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
16750 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
16760 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
16770 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
16780 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
16790 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
167a0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
167b0 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
167c0 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
167d0 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
167e0 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
167f0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
16800 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
16810 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
16820 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
16830 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
16840 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
16850 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
16860 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
16870 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
16880 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
16890 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
168a0 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
168b0 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
168c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
168d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
168e0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
168f0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
16900 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
16910 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
16920 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
16930 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
16940 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
16950 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16960 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
16970 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
16980 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
16990 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
169a0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
169b0 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
169c0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
169d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
169e0 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
169f0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
16a00 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
16a10 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
16a20 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
16a30 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
16a40 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
16a50 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
16a60 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
16a70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16a80 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
16a90 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
16aa0 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
16ab0 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
16ac0 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
16ad0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
16ae0 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
16af0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
16b00 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16b10 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
16b20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
16b30 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
16b40 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
16b50 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
16b60 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
16b70 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
16b80 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
16b90 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
16ba0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16bb0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
16bc0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
16bd0 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
16be0 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
16bf0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
16c00 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
16c10 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
16c20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16c30 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20  LOOKASIDE       
16c40 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69  1001  /* void* i
16c50 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
16c60 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
16c70 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20  G_ENABLE_FKEY   
16c80 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69    1002  /* int i
16c90 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
16ca0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
16cb0 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31  NABLE_TRIGGER  1
16cc0 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  003  /* int int*
16cd0 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   */.../*.** CAPI
16ce0 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
16cf0 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
16d00 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
16d10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
16d20 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
16d30 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65  _codes() routine
16d40 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
16d50 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74  bles the.** [ext
16d60 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
16d70 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53  es] feature of S
16d80 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65  QLite. ^The exte
16d90 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
16da0 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65  odes are disable
16db0 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
16dc0 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70   historical comp
16dd0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e  atibility..*/.in
16de0 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
16df0 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
16e00 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
16e10 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
16e20 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
16e30 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e  rt Rowid.**.** ^
16e40 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f  Each entry in mo
16e50 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73  st SQLite tables
16e60 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49   (except for [WI
16e70 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
16e80 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e  les).** has a un
16e90 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
16ea0 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
16eb0 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
16ec0 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
16ed0 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
16ee0 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
16ef0 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
16f00 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
16f10 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
16f20 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
16f30 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
16f40 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
16f50 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
16f60 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
16f70 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
16f80 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
16f90 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
16fa0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
16fb0 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
16fc0 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
16fd0 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
16fe0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
16ff0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17000 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72  t_rowid(D) inter
17010 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
17020 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
17030 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
17040 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
17050 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64  RT] into a rowid
17060 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75   table or [virtu
17070 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20  al table].** on 
17080 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17090 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72  ion D..** ^Inser
170a0 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
170b0 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
170c0 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e  re not recorded.
170d0 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  .** ^If no succe
170e0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
170f0 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
17100 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
17110 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64  ccurred on the d
17120 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17130 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73  on D, .** then s
17140 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
17150 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75  rt_rowid(D) retu
17160 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
17170 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
17180 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
17190 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68   trigger or with
171a0 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  in a [virtual ta
171b0 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20  ble].** method, 
171c0 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
171d0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
171e0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
171f0 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
17200 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
17210 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
17220 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
17230 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
17240 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
17250 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
17260 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73  able method ends
17270 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
17280 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
17290 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
172a0 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
172b0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
172c0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a  er or virtual.**
172d0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65   table method be
172e0 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  gan.)^.**.** ^An
172f0 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
17300 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
17310 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
17320 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
17330 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
17340 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
17350 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
17360 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
17370 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
17380 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
17390 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
173a0 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
173b0 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
173c0 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
173d0 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
173e0 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
173f0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
17400 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
17410 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
17420 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
17430 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
17440 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
17450 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
17460 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
17470 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
17480 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
17490 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
174a0 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
174b0 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
174c0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
174d0 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
174e0 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
174f0 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
17500 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
17510 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
17520 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
17530 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
17540 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
17550 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
17560 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
17570 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
17580 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
17590 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
175a0 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
175b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
175c0 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
175d0 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
175e0 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
175f0 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
17600 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
17610 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
17620 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
17630 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
17640 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
17650 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17660 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
17670 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
17680 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
17690 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
176a0 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
176b0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
176c0 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
176d0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
176e0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
176f0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
17700 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
17710 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
17720 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
17730 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
17740 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
17750 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
17760 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
17770 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
17780 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
17790 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
177a0 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
177b0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
177c0 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e  Modified.**.** ^
177d0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
177e0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
177f0 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
17800 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a  d, inserted or.*
17810 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  * deleted by the
17820 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
17830 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
17840 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
17850 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f  E.** statement o
17860 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
17870 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66  onnection specif
17880 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20  ied by the only 
17890 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45  parameter..** ^E
178a0 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
178b0 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
178c0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
178d0 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c  t modify the val
178e0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
178f0 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  y this function.
17900 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61  .**.** ^Only cha
17910 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74  nges made direct
17920 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54  ly by the INSERT
17930 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
17940 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
17950 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d  .** considered -
17960 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   auxiliary chang
17970 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52  es caused by [CR
17980 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
17990 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66  riggers], .** [f
179a0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
179b0 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d  ns] or [REPLACE]
179c0 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
179d0 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63  lution are not c
179e0 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43  ounted..** .** C
179f0 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
17a00 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
17a10 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e  epted by .** [IN
17a20 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
17a30 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72   | INSTEAD OF tr
17a40 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20  iggers] are not 
17a50 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61  counted. ^The va
17a60 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64  lue .** returned
17a70 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
17a80 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c  ges() immediatel
17a90 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52  y after an INSER
17aa0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a  T, UPDATE or .**
17ab0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
17ac0 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20  t run on a view 
17ad0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20  is always zero. 
17ae0 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
17af0 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61  e to real .** ta
17b00 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  bles are counted
17b10 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61  ..**.** Things a
17b20 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61  re more complica
17b30 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74  ted if the sqlit
17b40 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
17b50 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63  ction is.** exec
17b60 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69  uted while a tri
17b70 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20  gger program is 
17b80 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61  running. This ma
17b90 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a  y happen if the.
17ba0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  ** program uses 
17bb0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
17bc0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72  QL function], or
17bd0 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63   if some other c
17be0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
17bf0 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69  ion invokes sqli
17c00 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69  te3_changes() di
17c10 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61  rectly. Essentia
17c20 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e  lly:.** .** <ul>
17c30 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66  .**   <li> ^(Bef
17c40 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74  ore entering a t
17c50 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74  rigger program t
17c60 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
17c70 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73  d by.**        s
17c80 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
17c90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76   function is sav
17ca0 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72  ed. After the tr
17cb0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a  igger program .*
17cc0 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e  *        has fin
17cd0 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69  ished, the origi
17ce0 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73  nal value is res
17cf0 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20  tored.)^.** .** 
17d00 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20    <li> ^(Within 
17d10 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
17d20 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55  m each INSERT, U
17d30 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45  PDATE and DELETE
17d40 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74   .**        stat
17d50 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76  ement sets the v
17d60 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
17d70 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
17d80 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70  () .**        up
17d90 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73  on completion as
17da0 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72   normal. Of cour
17db0 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77  se, this value w
17dc0 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  ill not include 
17dd0 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63  .**        any c
17de0 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64  hanges performed
17df0 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73   by sub-triggers
17e00 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33  , as the sqlite3
17e10 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
17e20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c        value will
17e30 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65   be saved and re
17e40 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63  stored after eac
17e50 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61  h sub-trigger ha
17e60 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c  s run.)^.** </ul
17e70 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d  >.** .** ^This m
17e80 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65  eans that if the
17e90 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66   changes() SQL f
17ea0 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69  unction (or simi
17eb0 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20  lar) is used.** 
17ec0 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53  by the first INS
17ed0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
17ee0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
17ef0 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
17f00 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73  , it .** returns
17f10 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65   the value as se
17f20 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69  t when the calli
17f30 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67  ng statement beg
17f40 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  an executing..**
17f50 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20   ^If it is used 
17f60 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72  by the second or
17f70 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68   subsequent such
17f80 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
17f90 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20  n a trigger .** 
17fa0 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c  program, the val
17fb0 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c  ue returned refl
17fc0 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20  ects the number 
17fd0 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
17fe0 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76   by the .** prev
17ff0 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44  ious INSERT, UPD
18000 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
18010 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
18020 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
18030 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
18040 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
18050 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
18060 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
18070 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
18080 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
18090 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
180a0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
180b0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
180c0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
180d0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
180e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
180f0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
18100 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
18110 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
18120 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
18130 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
18140 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
18150 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
18160 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
18170 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
18180 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
18190 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
181a0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
181b0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
181c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74   returns the tot
181d0 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  al number of row
181e0 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69  s inserted, modi
181f0 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  fied or.** delet
18200 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52  ed by all [INSER
18210 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  T], [UPDATE] or 
18220 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
18230 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a  nts completed.**
18240 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62   since the datab
18250 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
18260 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75  as opened, inclu
18270 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75  ding those execu
18280 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ted as.** part o
18290 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  f trigger progra
182a0 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61  ms. ^Executing a
182b0 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
182c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
182d0 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63  * does not affec
182e0 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
182f0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
18300 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e  total_changes().
18310 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  .** .** ^Changes
18320 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
18330 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
18340 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75  tions] are inclu
18350 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f  ded in the.** co
18360 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d  unt, but those m
18370 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52  ade as part of R
18380 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
18390 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
183a0 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65  .** not. ^Change
183b0 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
183c0 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
183d0 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74   by INSTEAD OF t
183e0 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20  riggers .** are 
183f0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
18400 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
18410 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
18420 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
18430 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
18440 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
18450 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
18460 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
18470 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
18480 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
18490 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
184a0 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
184b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
184c0 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
184d0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
184e0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
184f0 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
18500 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
18510 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
18520 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
18530 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
18540 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
18550 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
18560 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
18570 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
18580 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  Query.**.** ^Thi
18590 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
185a0 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
185b0 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
185c0 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
185d0 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
185e0 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
185f0 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
18600 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
18610 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
18620 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
18630 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
18640 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
18650 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
18660 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
18670 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
18680 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
18690 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
186a0 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61  .**.** ^It is sa
186b0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
186c0 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
186d0 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
186e0 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
186f0 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
18700 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
18710 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
18720 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
18730 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
18740 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
18750 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
18760 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
18770 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
18780 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
18790 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
187a0 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
187b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  s..**.** ^If an 
187c0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
187d0 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
187e0 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
187f0 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
18800 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
18810 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
18820 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
18830 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
18840 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
18850 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
18860 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
18870 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  tion..**.** ^An 
18880 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
18890 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
188a0 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
188b0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
188c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74  ..** ^If the int
188d0 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
188e0 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53  ration is an INS
188f0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
18900 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69  DELETE.** that i
18910 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
18920 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
18930 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
18940 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a  e transaction.**
18950 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
18960 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
18970 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
18980 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18990 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65  (D) call is in e
189a0 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20  ffect until all 
189b0 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
189c0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
189d0 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  nts on [database
189e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63   connection] D c
189f0 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e  omplete.  ^Any n
18a00 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
18a10 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
18a20 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
18a30 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18a40 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
18a50 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
18a60 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
18a70 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
18a80 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
18a90 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
18aa0 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
18ab0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
18ac0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
18ad0 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74  .  ^New SQL stat
18ae0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
18af0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
18b00 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
18b10 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
18b20 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
18b30 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
18b40 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
18b50 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20  errupt()..** ^A 
18b60 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
18b70 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61  interrupt(D) tha
18b80 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68  t occurs when th
18b90 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69  ere are no runni
18ba0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
18bb0 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20  ents is a no-op 
18bc0 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63  and has no effec
18bd0 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t on SQL stateme
18be0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
18bf0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
18c00 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
18c10 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72  upt() call retur
18c20 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ns..**.** If the
18c30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18c40 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
18c50 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
18c60 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75  rupt()].** is ru
18c70 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
18c80 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
18c90 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69  y happen..*/.voi
18ca0 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
18cb0 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
18cc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18cd0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
18ce0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
18cf0 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
18d00 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
18d10 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
18d20 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
18d30 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
18d40 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
18d50 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
18d60 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
18d70 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
18d80 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
18d90 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
18da0 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
18db0 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
18dc0 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
18dd0 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
18de0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
18df0 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68  s return 1 if th
18e00 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
18e10 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
18e20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
18e30 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74  tatement.  ^A st
18e40 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
18e50 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
18e60 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
18e70 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
18e80 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
18e90 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a   a prefix of a.*
18ea0 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52  * well-formed CR
18eb0 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
18ec0 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f  tement.  ^Semico
18ed0 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
18ee0 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
18ef0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
18f00 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
18f10 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
18f20 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
18f30 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
18f40 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
18f50 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
18f60 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
18f70 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
18f80 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
18f90 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
18fa0 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
18fb0 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a  .  ^Whitespace.*
18fc0 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74  * and comments t
18fd0 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66  hat follow the f
18fe0 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  inal semicolon a
18ff0 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  re ignored..**.*
19000 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
19010 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68  s return 0 if th
19020 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69  e statement is i
19030 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20  ncomplete.  ^If 
19040 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
19050 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
19060 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
19070 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
19080 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
19090 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
190a0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
190b0 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
190c0 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
190d0 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
190e0 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ct SQL..**.** ^(
190f0 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
19100 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
19110 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
19120 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
19130 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
19140 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
19150 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
19160 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
19170 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
19180 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
19190 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
191a0 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
191b0 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
191c0 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
191d0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
191e0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
191f0 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
19200 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
19210 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
19220 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
19230 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
19240 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  mplete.)^.**.** 
19250 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
19260 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
19270 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
19280 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
19290 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
192a0 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
192b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
192c0 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
192d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
192e0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
192f0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
19300 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73   order..*/.int s
19310 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
19320 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
19330 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
19340 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
19350 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
19360 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
19370 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
19380 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
19390 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20  _BUSY Errors.** 
193a0 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d  KEYWORDS: {busy-
193b0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
193c0 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d  } {busy handler}
193d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
193e0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
193f0 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20  (D,X,P) routine 
19400 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
19410 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68  function X.** th
19420 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
19430 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ked with argumen
19440 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  t P whenever.** 
19450 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
19460 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64  de to access a d
19470 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73  atabase table as
19480 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
19490 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
194a0 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e  ction] D when an
194b0 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
194c0 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74  or process has t
194d0 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e  he table locked.
194e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
194f0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69  busy_handler() i
19500 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
19510 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a   to implement.**
19520 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
19530 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50  imeout()] and [P
19540 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
19550 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ut]..**.** ^If t
19560 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
19570 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
19580 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
19590 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
195a0 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
195b0 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
195c0 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
195d0 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
195e0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
195f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
19600 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
19610 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
19620 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
19630 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
19640 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
19650 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
19660 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
19670 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
19680 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
19690 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
196a0 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
196b0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
196c0 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
196d0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
196e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
196f0 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
19700 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
19710 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
19720 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74  previously for t
19730 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20  he same locking 
19740 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
19750 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
19760 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
19770 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
19780 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
19790 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
197a0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
197b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20  SQLITE_BUSY] is 
197c0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74  returned.** to t
197d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a  he application..
197e0 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
197f0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
19800 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
19810 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
19820 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
19830 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
19840 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
19850 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
19860 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
19870 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
19880 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
19890 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
198a0 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
198b0 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
198c0 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
198d0 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
198e0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
198f0 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
19900 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
19910 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
19920 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
19930 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
19940 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  SY].** to the ap
19950 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61  plication instea
19960 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
19970 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  e .** busy handl
19980 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
19990 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
199a0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
199b0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
199c0 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
199d0 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
199e0 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
199f0 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
19a00 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
19a10 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
19a20 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
19a30 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
19a40 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
19a50 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
19a60 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
19a70 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
19a80 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
19a90 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
19aa0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
19ab0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
19ac0 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
19ad0 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
19ae0 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
19af0 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
19b00 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
19b10 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
19b20 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
19b30 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
19b40 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
19b50 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
19b60 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
19b70 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
19b80 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
19b90 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
19ba0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
19bb0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
19bc0 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
19bd0 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
19be0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
19bf0 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
19c00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
19c10 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
19c20 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
19c30 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
19c40 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
19c50 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
19c60 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
19c70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19c80 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
19c90 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
19ca0 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
19cb0 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
19cc0 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
19cd0 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
19ce0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
19cf0 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c  ut()].** or eval
19d00 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62  uating [PRAGMA b
19d10 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77  usy_timeout=N] w
19d20 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a  ill change the.*
19d30 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61  * busy handler a
19d40 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e  nd thus clear an
19d50 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  y previously set
19d60 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
19d70 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
19d80 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
19d90 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
19da0 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
19db0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
19dc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
19dd0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
19de0 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74   handler.  In ot
19df0 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68  her words,.** th
19e00 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
19e10 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  s not reentrant.
19e20 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
19e30 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
19e40 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
19e50 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
19e60 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
19e70 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
19e80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19e90 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
19ea0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
19eb0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
19ec0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
19ed0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
19ee0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
19ef0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
19f00 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
19f10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
19f20 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
19f30 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
19f40 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
19f50 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
19f60 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
19f70 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
19f80 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
19f90 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
19fa0 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
19fb0 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
19fc0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
19fd0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
19fe0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
19ff0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1a000 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
1a010 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
1a020 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
1a030 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1a040 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1a050 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
1a060 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
1a070 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
1a080 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
1a090 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
1a0a0 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  BUSY]..**.** ^Ca
1a0b0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
1a0c0 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
1a0d0 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
1a0e0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
1a0f0 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
1a100 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
1a110 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1a120 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1a130 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
1a140 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
1a150 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1a160 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20  nection] at any 
1a170 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
1a180 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
1a190 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
1a1a0 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
1a1b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1a1c0 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
1a1d0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
1a1e0 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
1a1f0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1a200 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
1a210 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1a220 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1a230 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71  meout].*/.int sq
1a240 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1a250 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
1a260 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
1a270 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
1a280 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
1a290 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
1a2a0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1a2b0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1a2c0 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1a2d0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1a2e0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1a2f0 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1a300 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1a310 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1a320 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1a330 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1a340 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1a350 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1a360 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1a370 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1a380 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1a390 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1a3a0 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1a3b0 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1a3c0 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1a3d0 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1a3e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1a3f0 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1a400 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1a410 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1a420 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1a430 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1a440 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1a450 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1a460 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1a470 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1a480 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1a490 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1a4a0 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1a4b0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1a4c0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1a4d0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1a4e0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1a4f0 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1a500 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1a510 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1a520 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1a530 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1a540 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1a550 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1a560 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1a570 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1a580 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1a590 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1a5a0 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1a5b0 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1a5c0 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1a5d0 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1a5e0 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1a5f0 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1a600 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1a610 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1a620 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1a630 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1a640 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1a650 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1a660 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1a670 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1a680 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1a690 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1a6a0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1a6b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1a6c0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1a6d0 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1a6e0 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1a6f0 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1a700 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1a710 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1a720 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1a730 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1a740 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1a750 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1a760 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1a770 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1a780 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1a790 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1a7a0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1a7b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1a7c0 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1a7d0 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1a7e0 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1a7f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1a800 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1a810 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1a820 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1a830 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1a840 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1a850 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1a860 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1a870 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1a880 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1a890 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1a8a0 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1a8b0 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1a8c0 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1a8d0 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1a8e0 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1a8f0 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1a900 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1a910 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1a920 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1a930 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1a940 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1a950 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1a960 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1a970 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a980 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1a990 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a9a0 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1a9b0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a9c0 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1a9d0 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1a9e0 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1a9f0 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1aa00 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1aa10 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1aa20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1aa30 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1aa40 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1aa50 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1aa60 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1aa70 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1aa80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1aa90 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1aaa0 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1aab0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1aac0 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1aad0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1aae0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1aaf0 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1ab00 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1ab10 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1ab20 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1ab30 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1ab40 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1ab50 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1ab60 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1ab70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1ab80 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1ab90 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1aba0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1abb0 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1abc0 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1abd0 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1abe0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1abf0 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1ac00 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1ac10 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1ac20 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1ac30 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1ac40 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1ac50 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1ac60 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1ac70 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1ac80 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1ac90 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1aca0 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1acb0 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1acc0 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1acd0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1ace0 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1acf0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1ad00 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1ad10 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1ad20 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1ad30 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1ad40 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1ad50 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1ad60 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1ad70 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1ad80 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1ad90 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1ada0 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1adb0 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1adc0 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1add0 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1ade0 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1adf0 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1ae00 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1ae10 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1ae20 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1ae30 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1ae40 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1ae50 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1ae60 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1ae70 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1ae80 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1ae90 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1aea0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1aeb0 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1aec0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1aed0 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  g()]..*/.int sql
1aee0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1aef0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1af00 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1af10 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1af20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1af30 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1af40 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1af50 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1af60 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1af70 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1af80 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1af90 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1afa0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1afb0 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1afc0 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1afd0 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1afe0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1aff0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1b000 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1b010 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1b020 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1b030 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1b040 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1b050 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
1b060 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
1b070 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
1b080 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
1b090 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1b0a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1b0b0 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
1b0c0 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
1b0d0 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
1b0e0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
1b0f0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1b100 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  library..**.** ^
1b110 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
1b120 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
1b130 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
1b140 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
1b150 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
1b160 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
1b170 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
1b180 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
1b190 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
1b1a0 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
1b1b0 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
1b1c0 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
1b1d0 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
1b1e0 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
1b1f0 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
1b200 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
1b210 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1b220 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
1b230 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
1b240 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
1b250 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
1b260 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
1b270 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  The sqlite3_snpr
1b280 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1b290 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
1b2a0 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
1b2b0 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
1b2c0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
1b2d0 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
1b2e0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
1b2f0 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
1b300 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1b310 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
1b320 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
1b330 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1b340 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
1b350 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
1b360 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
1b370 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
1b380 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
1b390 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61  ().)^  This is a
1b3a0 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
1b3b0 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
1b3c0 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
1b3d0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
1b3e0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
1b3f0 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f  atibility.  ^(No
1b400 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
1b410 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1b420 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
1b430 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
1b440 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1b450 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
1b460 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
1b470 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
1b480 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57  the buffer.)^  W
1b490 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
1b4a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
1b4b0 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
1b4c0 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
1b4d0 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
1b4e0 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
1b4f0 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
1b500 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1b510 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1b520 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
1b530 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
1b540 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
1b550 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74  ** ^As long as t
1b560 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
1b570 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
1b580 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
1b590 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
1b5a0 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
1b5b0 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
1b5c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
1b5d0 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20    ^The first.** 
1b5e0 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
1b5f0 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
1b600 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
1b610 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
1b620 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
1b630 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
1b640 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
1b650 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
1b660 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
1b670 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
1b680 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
1b690 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1b6a0 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1b6b0 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20  ne is a varargs 
1b6c0 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74  version of sqlit
1b6d0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a  e3_snprintf()..*
1b6e0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1b6f0 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  nes all implemen
1b700 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  t some additiona
1b710 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20  l formatting.** 
1b720 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  options that are
1b730 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73   useful for cons
1b740 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61  tructing SQL sta
1b750 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20  tements..** All 
1b760 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69  of the usual pri
1b770 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67  ntf() formatting
1b780 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20   options apply. 
1b790 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68   In addition, th
1b7a0 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25  ere.** is are "%
1b7b0 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25  q", "%Q", and "%
1b7c0 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  z" options..**.*
1b7d0 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f  * ^(The %q optio
1b7e0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
1b7f0 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
1b800 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72  itutes a nul-ter
1b810 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1b820 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
1b830 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
1b840 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
1b850 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
1b860 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
1b870 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
1b880 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
1b890 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f  iteral.)^  By do
1b8a0 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
1b8b0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
1b8c0 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
1b8d0 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
1b8e0 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
1b8f0 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
1b900 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
1b910 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
1b920 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
1b930 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
1b940 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
1b950 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1b960 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1b970 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
1b980 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
1b990 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
1b9a0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1b9b0 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
1b9c0 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
1b9d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
1b9e0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1b9f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1ba00 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1ba10 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1ba20 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1ba30 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
1ba40 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1ba50 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1ba60 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1ba70 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1ba80 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1ba90 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1baa0 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
1bab0 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
1bac0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
1bad0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
1bae0 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
1baf0 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
1bb00 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
1bb10 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1bb20 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1bb30 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1bb40 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1bb50 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
1bb60 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
1bb70 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1bb80 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
1bb90 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
1bba0 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
1bbb0 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
1bbc0 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
1bbd0 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
1bbe0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
1bbf0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1bc00 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1bc10 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1bc20 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1bc30 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1bc40 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1bc50 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
1bc60 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
1bc70 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
1bc80 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
1bc90 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
1bca0 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
1bcb0 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
1bcc0 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
1bcd0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1bce0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  l..**.** ^(The %
1bcf0 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
1bd00 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
1bd10 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
1bd20 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
1bd30 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
1bd40 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
1bd50 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
1bd60 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
1bd70 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
1bd80 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
1bd90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
1bda0 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
1bdb0 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
1bdc0 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
1bdd0 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c   quotes).)^  So,
1bde0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
1bdf0 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
1be00 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1be10 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1be20 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1be30 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1be40 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1be50 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
1be60 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1be70 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1be80 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1be90 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1bea0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1beb0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
1bec0 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
1bed0 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
1bee0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
1bef0 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
1bf00 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
1bf10 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
1bf20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1bf30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a  .**.** ^(The "%z
1bf40 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1bf50 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22  ion works like "
1bf60 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65  %s" but with the
1bf70 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
1bf80 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
1bf90 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
1bfa0 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
1bfb0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
1bfc0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1bfd0 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
1bfe0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29  e input string.)
1bff0 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ^.*/.char *sqlit
1c000 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
1c010 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
1c020 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
1c030 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1c040 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
1c050 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
1c060 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1c070 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63  t char*, ...);.c
1c080 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e  har *sqlite3_vsn
1c090 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1c0a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  ,const char*, va
1c0b0 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _list);../*.** C
1c0c0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1c0d0 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
1c0e0 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
1c0f0 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
1c100 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
1c110 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
1c120 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
1c130 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
1c140 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
1c150 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
1c160 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
1c170 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
1c180 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
1c190 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
1c1a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1c1b0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
1c1c0 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
1c1d0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1c1e0 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
1c1f0 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
1c200 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1c210 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
1c220 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1c230 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
1c240 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
1c250 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
1c260 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1c270 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1c280 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
1c290 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
1c2a0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
1c2b0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
1c2c0 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
1c2d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1c2e0 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
1c2f0 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
1c300 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
1c310 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
1c320 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
1c330 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
1c340 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1c350 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1c360 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f  3_malloc64(N) ro
1c370 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74  utine works just
1c380 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33   like.** sqlite3
1c390 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70  _malloc(N) excep
1c3a0 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75  t that N is an u
1c3b0 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69  nsigned 64-bit i
1c3c0 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1c3d0 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32  * of a signed 32
1c3e0 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  -bit integer..**
1c3f0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
1c400 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
1c410 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
1c420 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
1c430 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
1c440 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1c450 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
1c460 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
1c470 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
1c480 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
1c490 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
1c4a0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
1c4b0 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
1c4c0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
1c4d0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
1c4e0 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
1c4f0 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
1c500 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
1c510 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
1c520 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
1c530 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
1c540 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
1c550 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
1c560 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
1c570 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
1c580 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
1c590 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1c5a0 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
1c5b0 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
1c5c0 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
1c5d0 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
1c5e0 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
1c5f0 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
1c600 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
1c610 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
1c620 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1c630 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
1c640 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
1c650 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
1c660 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c670 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1c680 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  lloc()..**.** ^T
1c690 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1c6a0 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  oc(X,N) interfac
1c6b0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1c6c0 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1c6d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c6e0 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61  n X to be at lea
1c6f0 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  st N bytes..** ^
1c700 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74  If the X paramet
1c710 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1c720 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73  alloc(X,N).** is
1c730 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1c740 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
1c750 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
1c760 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
1c770 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a  ite3_malloc(N)..
1c780 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72  ** ^If the N par
1c790 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1c7a0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1c7b0 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
1c7c0 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
1c7d0 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
1c7e0 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
1c7f0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1c800 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73  3_free(X)..** ^s
1c810 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1c820 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ,N) returns a po
1c830 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1c840 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1c850 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1c860 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1c870 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
1c880 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76  ent memory is av
1c890 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1c8a0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1c8b0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1c8c0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1c8d0 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1c8e0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1c8f0 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1c900 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1c910 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1c920 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1c930 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1c940 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1c950 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1c960 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1c970 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1c980 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
1c990 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c  d N is positive,
1c9a0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69   then the.** pri
1c9b0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1c9c0 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
1c9d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1c9e0 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e  ealloc64(X,N) in
1c9f0 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74  terfaces works t
1ca00 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
1ca10 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1ca20 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1ca30 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73   is a 64-bit uns
1ca40 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e  igned integer in
1ca50 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32  stead.** of a 32
1ca60 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1ca70 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58  ger..**.** ^If X
1ca80 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   is a memory all
1ca90 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73  ocation previous
1caa0 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
1cab0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1cac0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ),.** sqlite3_ma
1cad0 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65  lloc64(), sqlite
1cae0 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20  3_realloc(), or 
1caf0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1cb00 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  4(), then.** sql
1cb10 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1cb20 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
1cb30 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c  f that memory al
1cb40 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65  location in byte
1cb50 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  s..** ^The value
1cb60 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1cb70 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69  ite3_msize(X) mi
1cb80 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68  ght be larger th
1cb90 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  an the number.**
1cba0 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73   of bytes reques
1cbb0 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61  ted when X was a
1cbc0 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58  llocated.  ^If X
1cbd0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1cbe0 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  er then.** sqlit
1cbf0 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1cc00 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20  rns zero.  If X 
1cc10 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68  points to someth
1cc20 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a  ing that is not.
1cc30 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  ** the beginning
1cc40 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
1cc50 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20  ation, or if it 
1cc60 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d  points to a form
1cc70 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65  erly.** valid me
1cc80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1cc90 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65  that has now bee
1cca0 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68  n freed, then th
1ccb0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
1ccc0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1ccd0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  ) is undefined a
1cce0 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d  nd possibly harm
1ccf0 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ful..**.** ^The 
1cd00 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
1cd10 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1cd20 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61  c(), sqlite3_rea
1cd30 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
1cd40 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61  e3_malloc64(), a
1cd50 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
1cd60 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77  oc64().** is alw
1cd70 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
1cd80 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
1cd90 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
1cda0 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
1cdb0 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
1cdc0 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
1cdd0 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
1cde0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
1cdf0 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
1ce00 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
1ce10 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
1ce20 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
1ce30 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
1ce40 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
1ce50 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
1ce60 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
1ce70 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
1ce80 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
1ce90 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
1cea0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
1ceb0 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
1cec0 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
1ced0 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
1cee0 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
1cef0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
1cf00 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
1cf10 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
1cf20 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1cf30 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77  7.10, the Window
1cf40 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
1cf50 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  ayer called.** t
1cf60 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
1cf70 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
1cf80 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
1cf90 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
1cfa0 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
1cfb0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
1cfc0 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
1cfd0 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
1cfe0 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
1cff0 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
1d000 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
1d010 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
1d020 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
1d030 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72  ation errors wer
1d040 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
1d050 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70  ** they were rep
1d060 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
1d070 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
1d080 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
1d090 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
1d0a0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
1d0b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1d0c0 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
1d0d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1d0e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1d0f0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
1d100 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
1d110 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
1d120 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1d130 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
1d140 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1d150 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
1d160 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d170 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
1d180 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
1d190 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
1d1a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
1d1b0 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
1d1c0 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
1d1d0 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
1d1e0 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
1d1f0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
1d200 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1d210 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
1d220 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
1d230 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1d240 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
1d250 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
1d260 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69  loc64(sqlite3_ui
1d270 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  nt64);.void *sql
1d280 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
1d290 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  d*, int);.void *
1d2a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1d2b0 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  4(void*, sqlite3
1d2c0 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  _uint64);.void s
1d2d0 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
1d2e0 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74  *);.sqlite3_uint
1d2f0 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  64 sqlite3_msize
1d300 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1d310 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1d320 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1d330 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1d340 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1d350 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1d360 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1d370 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1d380 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1d390 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1d3a0 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1d3b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1d3c0 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1d3d0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1d3e0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1d3f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1d400 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1d410 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1d420 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1d430 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1d440 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1d450 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1d460 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1d470 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1d480 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1d490 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1d4a0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1d4b0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1d4c0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1d4d0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1d4e0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1d4f0 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1d500 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1d510 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1d520 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1d530 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1d540 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1d550 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1d560 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1d570 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1d580 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1d590 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1d5a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1d5b0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1d5c0 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1d5d0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1d5e0 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1d5f0 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1d600 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1d610 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1d620 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1d630 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1d640 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1d650 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1d660 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1d670 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1d680 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1d690 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1d6a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1d6b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1d6c0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1d6d0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1d6e0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1d6f0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1d700 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1d710 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1d720 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1d730 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1d740 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
1d750 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1d760 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
1d770 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1d780 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1d790 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
1d7a0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
1d7b0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
1d7c0 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
1d7d0 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
1d7e0 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
1d7f0 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
1d800 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
1d810 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
1d820 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
1d830 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
1d840 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
1d850 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
1d860 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
1d870 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
1d880 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
1d890 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
1d8a0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
1d8b0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
1d8c0 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
1d8d0 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
1d8e0 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
1d8f0 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
1d900 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
1d910 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
1d920 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
1d930 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
1d940 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
1d950 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
1d960 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
1d970 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
1d980 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
1d990 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  er P..** ^The P 
1d9a0 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65  parameter can be
1d9b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1d9c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20  .**.** ^If this 
1d9d0 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20  routine has not 
1d9e0 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  been previously 
1d9f0 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65  called or if the
1da00 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c   previous.** cal
1da10 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61  l had N less tha
1da20 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20  n one or a NULL 
1da30 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74  pointer for P, t
1da40 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a  hen the PRNG is.
1da50 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  ** seeded using 
1da60 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
1da70 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61  ned from the xRa
1da80 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1da90 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  of.** the defaul
1daa0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1dab0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74  object..** ^If t
1dac0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
1dad0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1dae0 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f   had an N of 1 o
1daf0 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20  r more and a.** 
1db00 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20  non-NULL P then 
1db10 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
1db20 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
1db30 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
1db40 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
1db50 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
1db60 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
1db70 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
1db80 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
1db90 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
1dba0 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
1dbb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1dbc0 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
1dbd0 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
1dbe0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  cks.**.** ^This 
1dbf0 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
1dc00 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  s an authorizer 
1dc10 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
1dc20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1dc30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1dc40 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
1dc50 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1dc60 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
1dc70 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1dc80 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
1dc90 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
1dca0 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
1dcb0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1dcc0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1dcd0 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
1dce0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1dcf0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
1dd00 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
1dd10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1dd20 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
1dd30 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
1dd40 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
1dd50 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
1dd60 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
1dd70 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
1dd80 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
1dd90 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
1dda0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ddb0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
1ddc0 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
1ddd0 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
1dde0 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
1ddf0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
1de00 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
1de10 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
1de20 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
1de30 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1de40 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
1de50 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
1de60 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
1de70 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1de80 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
1de90 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
1dea0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
1deb0 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
1dec0 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
1ded0 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
1dee0 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
1def0 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
1df00 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1df10 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
1df20 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
1df30 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
1df40 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
1df50 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
1df60 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
1df70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1df80 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1df90 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1dfa0 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
1dfb0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1dfc0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1dfd0 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
1dfe0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1dff0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
1e000 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
1e010 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
1e020 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
1e030 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
1e040 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1e050 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
1e060 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1e070 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1e080 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1e090 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
1e0a0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
1e0b0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1e0c0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
1e0d0 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
1e0e0 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
1e0f0 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
1e100 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1e110 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1e120 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
1e130 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
1e140 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
1e150 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
1e160 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
1e170 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
1e180 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
1e190 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1e1a0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1e1b0 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
1e1c0 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
1e1d0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
1e1e0 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
1e1f0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1e200 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
1e210 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
1e220 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
1e230 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
1e240 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1e250 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
1e260 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
1e270 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
1e280 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
1e290 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
1e2a0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
1e2b0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1e2c0 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
1e2d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1e2e0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
1e2f0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
1e300 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
1e310 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
1e320 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
1e330 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
1e340 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
1e350 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
1e360 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
1e370 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
1e380 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
1e390 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
1e3a0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
1e3b0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
1e3c0 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
1e3d0 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
1e3e0 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
1e3f0 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
1e400 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
1e410 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
1e420 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1e430 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
1e440 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
1e450 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1e460 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1e470 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
1e480 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
1e490 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
1e4a0 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
1e4b0 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
1e4c0 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
1e4d0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
1e4e0 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
1e4f0 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
1e500 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
1e510 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1e520 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
1e530 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
1e540 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
1e550 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
1e560 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
1e570 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
1e580 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
1e590 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
1e5a0 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
1e5b0 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
1e5c0 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
1e5d0 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
1e5e0 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
1e5f0 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
1e600 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
1e610 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
1e620 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
1e630 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
1e640 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
1e650 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
1e660 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
1e670 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
1e680 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1e690 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
1e6a0 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
1e6b0 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
1e6c0 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
1e6d0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
1e6e0 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
1e6f0 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
1e700 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
1e710 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
1e720 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
1e730 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1e740 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
1e750 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
1e760 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
1e770 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
1e780 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
1e790 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1e7a0 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
1e7b0 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
1e7c0 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
1e7d0 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
1e7e0 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
1e7f0 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
1e800 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1e810 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
1e820 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
1e830 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
1e840 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1e850 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
1e860 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
1e870 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
1e880 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
1e890 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
1e8a0 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
1e8b0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
1e8c0 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
1e8d0 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
1e8e0 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
1e8f0 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
1e900 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
1e910 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
1e920 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
1e930 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
1e940 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
1e950 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
1e960 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
1e970 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
1e980 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1e990 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1e9a0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1e9b0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1e9c0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1e9d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1e9e0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
1e9f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ea00 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
1ea10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ea20 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1ea30 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
1ea40 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
1ea50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ea60 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
1ea70 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
1ea80 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
1ea90 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
1eaa0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1eab0 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
1eac0 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
1ead0 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
1eae0 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
1eaf0 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
1eb00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1eb10 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
1eb20 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
1eb30 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
1eb40 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
1eb50 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
1eb60 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
1eb70 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1eb80 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
1eb90 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
1eba0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
1ebb0 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
1ebc0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ebd0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1ebe0 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
1ebf0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ec00 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1ec10 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
1ec20 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
1ec30 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
1ec40 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
1ec50 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
1ec60 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
1ec70 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
1ec80 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
1ec90 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
1eca0 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
1ecb0 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
1ecc0 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
1ecd0 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
1ece0 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
1ecf0 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
1ed00 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1ed10 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
1ed20 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
1ed30 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1ed40 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1ed50 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1ed60 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
1ed70 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
1ed80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ed90 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
1eda0 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
1edb0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1edc0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1edd0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1ede0 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
1edf0 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
1ee00 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
1ee10 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
1ee20 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
1ee30 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
1ee40 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
1ee50 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
1ee60 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
1ee70 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
1ee80 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1ee90 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1eea0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
1eeb0 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
1eec0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1eed0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
1eee0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
1eef0 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
1ef00 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c   [conflict resol
1ef10 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72  ution mode].** r
1ef20 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65  eturned from the
1ef30 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
1ef40 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
1ef50 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
1ef60 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
1ef70 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
1ef80 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1ef90 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
1efa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1efb0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
1efc0 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
1efd0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
1efe0 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
1eff0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1f000 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
1f010 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
1f020 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1f030 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
1f040 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
1f050 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
1f060 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
1f070 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
1f080 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
1f090 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
1f0a0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
1f0b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1f0c0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1f0d0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
1f0e0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
1f0f0 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
1f100 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
1f110 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
1f120 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
1f130 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
1f140 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1f150 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
1f160 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
1f170 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
1f180 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
1f190 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
1f1a0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
1f1b0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
1f1c0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
1f1d0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1f1e0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
1f1f0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1f200 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
1f210 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
1f220 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
1f230 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
1f240 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
1f250 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1f260 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
1f270 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1f280 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1f290 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1f2a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1f2b0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
1f2c0 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
1f2d0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
1f2e0 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
1f2f0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1f300 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
1f310 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
1f320 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
1f330 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
1f340 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
1f350 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
1f360 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
1f370 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
1f380 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
1f390 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
1f3a0 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
1f3b0 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
1f3c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f3d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f3e0 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
1f3f0 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
1f400 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
1f410 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
1f420 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
1f430 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1f440 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1f450 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f460 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
1f470 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
1f480 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f490 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f4a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f4b0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1f4c0 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
1f4d0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1f4e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f4f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f500 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1f510 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
1f520 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f530 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f540 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f550 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
1f560 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
1f570 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1f580 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f590 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f5a0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
1f5b0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
1f5c0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1f5d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f5e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f5f0 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
1f600 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
1f610 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1f620 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f630 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1f640 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
1f650 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
1f660 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1f670 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f680 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1f690 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
1f6a0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
1f6b0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f6c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f6d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f6e0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
1f6f0 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
1f700 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1f710 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f720 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f730 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1f740 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
1f750 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f760 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f770 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f780 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
1f790 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
1f7a0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1f7b0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f7c0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1f7d0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
1f7e0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1f7f0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1f800 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f810 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1f820 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
1f830 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1f840 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1f850 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f860 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1f870 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
1f880 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1f890 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f8a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f8b0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
1f8c0 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
1f8d0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1f8e0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1f8f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f900 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
1f910 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
1f920 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1f930 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f940 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f950 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
1f960 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
1f970 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f980 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f990 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f9a0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
1f9b0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
1f9c0 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
1f9d0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
1f9e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f9f0 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
1fa00 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
1fa10 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1fa20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1fa30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fa40 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
1fa50 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
1fa60 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
1fa70 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1fa80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fa90 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
1faa0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
1fab0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
1fac0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1fad0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fae0 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
1faf0 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
1fb00 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
1fb10 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
1fb20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1fb30 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
1fb40 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
1fb50 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
1fb60 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1fb70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1fb80 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1fb90 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
1fba0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
1fbb0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1fbc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
1fbd0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
1fbe0 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
1fbf0 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
1fc00 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1fc10 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
1fc20 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
1fc30 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
1fc40 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1fc50 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1fc60 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
1fc70 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
1fc80 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
1fc90 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1fca0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1fcb0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1fcc0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
1fcd0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
1fce0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1fcf0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1fd00 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
1fd10 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
1fd20 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1fd30 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1fd40 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1fd50 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
1fd60 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
1fd70 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1fd80 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
1fd90 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
1fda0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
1fdb0 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
1fdc0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1fdd0 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
1fde0 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
1fdf0 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
1fe00 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
1fe10 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
1fe20 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
1fe30 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20  ITE_RECURSIVE   
1fe40 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a           33   /*
1fe50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1fe60 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1fe70 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1fe80 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
1fe90 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
1fea0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
1feb0 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
1fec0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1fed0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
1fee0 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
1fef0 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
1ff00 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
1ff10 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
1ff20 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1ff30 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1ff40 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1ff50 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1ff60 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
1ff70 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
1ff80 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
1ff90 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
1ffa0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
1ffb0 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
1ffc0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
1ffd0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1ffe0 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
1fff0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
20000 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
20010 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
20020 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
20030 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
20040 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
20050 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
20060 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
20070 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
20080 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
20090 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
200a0 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
200b0 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
200c0 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
200d0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
200e0 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
200f0 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
20100 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  * The [SQLITE_TR
20110 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
20120 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
20130 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
20140 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20  to limit.** the 
20150 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64  length of [bound
20160 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61   parameter] expa
20170 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74  nsion in the out
20180 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74  put of sqlite3_t
20190 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  race()..**.** ^T
201a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
201b0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
201c0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
201d0 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
201e0 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
201f0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
20200 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
20210 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
20220 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
20230 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
20240 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
20250 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
20260 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
20270 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
20280 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
20290 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
202a0 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
202b0 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
202c0 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
202d0 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
202e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
202f0 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
20300 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
20310 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
20320 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
20330 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
20340 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
20350 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
20360 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
20370 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
20380 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
20390 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
203a0 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
203b0 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
203c0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
203d0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
203e0 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
203f0 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
20400 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
20410 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
20420 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
20430 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
20440 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
20450 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
20460 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
20470 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
20480 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
20490 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
204a0 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
204b0 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
204c0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
204d0 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
204e0 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
204f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
20500 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
20510 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
20520 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
20530 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
20540 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
20550 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
20560 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
20570 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
20580 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
20590 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
205a0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
205b0 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
205c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
205d0 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
205e0 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
205f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20600 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
20610 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
20620 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
20630 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
20640 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
20650 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
20660 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
20670 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
20680 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
20690 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
206a0 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
206b0 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
206c0 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
206d0 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e  he approximate n
206e0 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
206f0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
20700 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
20710 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
20720 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
20730 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
20740 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
20750 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65   X.  ^If N is le
20760 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e  ss than one then
20770 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a   the progress.**
20780 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61   handler is disa
20790 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  bled..**.** ^Onl
207a0 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
207b0 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
207c0 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
207d0 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
207e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
207f0 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
20800 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
20810 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
20820 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
20830 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
20840 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
20850 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
20860 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
20870 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
20880 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
20890 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
208a0 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
208b0 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
208c0 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
208d0 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
208e0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
208f0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
20900 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
20910 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
20920 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
20930 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
20940 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
20950 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
20960 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
20970 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
20980 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
20990 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
209a0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
209b0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
209c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
209d0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
209e0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
209f0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
20a00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20a10 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
20a20 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
20a30 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
20a40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20a50 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
20a60 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
20a70 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
20a80 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ..**.*/.void sql
20a90 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
20aa0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
20ab0 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
20ac0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
20ad0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
20ae0 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
20af0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
20b00 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
20b10 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
20b20 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
20b30 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62  e as specified b
20b40 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61  y the .** filena
20b50 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68  me argument. ^Th
20b60 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
20b70 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
20b80 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a  ed as UTF-8 for.
20b90 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
20ba0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
20bb0 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55  en_v2() and as U
20bc0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
20bd0 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65  ive byte.** orde
20be0 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  r for sqlite3_op
20bf0 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74  en16(). ^(A [dat
20c00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20c10 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
20c20 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
20c30 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
20c40 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
20c50 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
20c60 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
20c70 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
20c80 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
20c90 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
20ca0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
20cb0 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
20cc0 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
20cd0 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
20ce0 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
20cf0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
20d00 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e  ].** object.)^ ^
20d10 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  (If the database
20d20 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f   is opened (and/
20d30 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63  or created) succ
20d40 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a  essfully, then.*
20d50 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  * [SQLITE_OK] is
20d60 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
20d70 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
20d80 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
20d90 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71  d.)^ ^The.** [sq
20da0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
20db0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
20dc0 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
20dd0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
20de0 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
20df0 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
20e00 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
20e10 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67   error following
20e20 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e   a failure of an
20e30 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  y.** of the sqli
20e40 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69  te3_open() routi
20e50 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nes..**.** ^The 
20e60 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
20e70 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66   will be UTF-8 f
20e80 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65  or databases cre
20e90 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71  ated using.** sq
20ea0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
20eb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20ec0 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74  ).  ^The default
20ed0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61   encoding for da
20ee0 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74  tabases.** creat
20ef0 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
20f00 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62  _open16() will b
20f10 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  e UTF-16 in the 
20f20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
20f30 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  r..**.** Whether
20f40 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
20f50 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
20f60 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
20f70 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
20f80 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
20f90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20fa0 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
20fb0 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
20fc0 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
20fd0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
20fe0 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
20ff0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
21000 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
21010 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
21020 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
21030 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
21040 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
21050 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
21060 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
21070 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
21080 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
21090 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
210a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
210b0 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
210c0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
210d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
210e0 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
210f0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
21100 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
21110 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
21120 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
21130 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
21140 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
21150 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
21160 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
21170 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
21180 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
21190 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
211a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
211b0 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
211c0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
211d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
211e0 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
211f0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
21200 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
21210 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
21220 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
21230 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
21240 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
21250 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
21260 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
21270 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
21280 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
21290 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
212a0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
212b0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
212c0 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
212d0 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
212e0 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
212f0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
21300 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
21310 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
21320 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
21330 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
21340 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
21350 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
21360 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
21370 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
21380 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
21390 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
213a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
213b0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
213c0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
213d0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
213e0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
213f0 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
21400 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
21410 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
21420 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
21430 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
21440 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
21450 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
21460 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
21470 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
21480 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
21490 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
214a0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
214b0 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
214c0 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
214d0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
214e0 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
214f0 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
21500 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
21510 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
21520 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
21530 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
21540 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
21550 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
21560 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
21570 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
21580 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
21590 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
215a0 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
215b0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
215c0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
215d0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
215e0 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
215f0 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
21600 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
21610 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
21620 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
21630 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
21640 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
21650 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
21660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21670 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
21680 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
21690 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
216a0 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
216b0 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
216c0 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
216d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
216e0 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
216f0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
21700 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
21710 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
21720 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21730 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
21740 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
21750 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
21760 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
21770 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
21780 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
21790 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
217a0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
217b0 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
217c0 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
217d0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
217e0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
217f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21800 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
21810 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
21820 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
21830 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
21840 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
21850 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
21860 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
21870 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
21880 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
21890 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
218a0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
218b0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
218c0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
218d0 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
218e0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
218f0 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
21900 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
21910 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
21920 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
21930 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
21940 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
21950 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
21960 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
21970 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
21980 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
21990 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
219a0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
219b0 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
219c0 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
219d0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
219e0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
219f0 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
21a00 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
21a10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
21a20 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
21a30 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
21a40 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
21a50 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
21a60 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
21a70 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
21a80 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
21a90 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
21aa0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
21ab0 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
21ac0 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
21ad0 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
21ae0 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
21af0 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
21b00 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
21b10 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
21b20 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
21b30 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
21b40 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
21b50 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
21b60 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
21b70 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
21b80 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
21b90 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
21ba0 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
21bb0 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
21bc0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
21bd0 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
21be0 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
21bf0 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
21c00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
21c10 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
21c20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
21c30 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
21c40 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
21c50 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
21c60 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
21c70 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
21c80 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
21c90 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
21ca0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
21cb0 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
21cc0 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
21cd0 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
21ce0 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
21cf0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
21d00 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
21d10 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
21d20 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
21d30 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
21d40 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
21d50 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
21d60 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
21d70 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
21d80 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
21d90 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
21da0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
21db0 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
21dc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
21dd0 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
21de0 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
21df0 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
21e00 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
21e10 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
21e20 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
21e30 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
21e40 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
21e50 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
21e60 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
21e70 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
21e80 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
21e90 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
21ea0 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
21eb0 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
21ec0 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
21ed0 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
21ee0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
21ef0 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
21f00 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
21f10 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
21f20 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
21f30 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
21f40 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
21f50 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
21f60 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
21f70 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
21f80 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
21f90 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
21fa0 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
21fb0 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
21fc0 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
21fd0 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
21fe0 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
21ff0 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
22000 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
22010 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
22020 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
22030 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
22040 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
22050 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
22060 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
22070 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
22080 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
22090 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
220a0 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
220b0 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
220c0 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
220d0 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
220e0 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
220f0 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
22100 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
22110 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
22120 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
22130 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
22140 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
22150 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
22160 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
22170 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
22180 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
22190 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77  path. .** ^(On w
221a0 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73  indows, the firs
221b0 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
221c0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20  n absolute path 
221d0 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73  .** is a drive s
221e0 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e  pecification (e.
221f0 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a  g. "C:").)^.**.*
22200 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
22210 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
22220 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
22230 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
22240 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
22250 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
22260 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
22270 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
22280 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
22290 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
222a0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
222b0 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64  ]..** SQLite and
222c0 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56   its built-in [V
222d0 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20  FSes] interpret 
222e0 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  the.** following
222f0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
22300 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
22310 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f     <li> <b>vfs</
22320 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70  b>: ^The "vfs" p
22330 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
22340 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
22350 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20  the name of.**  
22360 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20     a VFS object 
22370 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68  that provides th
22380 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
22390 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
223a0 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20  t should.**     
223b0 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73  be used to acces
223c0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
223d0 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66  ile on disk. ^If
223e0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
223f0 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e  set to.**     an
22400 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68   empty string th
22410 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62  e default VFS ob
22420 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53  ject is used. ^S
22430 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
22440 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20  nown.**     VFS 
22450 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66  is an error. ^If
22460 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22470 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
22480 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73  he vfs option is
22490 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c  .**     present,
224a0 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70   then the VFS sp
224b0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
224c0 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63  ption takes prec
224d0 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20  edence over.**  
224e0 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73     the value pas
224f0 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
22500 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
22510 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22520 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
22530 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68  b>mode</b>: ^(Th
22540 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
22550 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
22560 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22  ither "ro", "rw"
22570 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20  ,.**     "rwc", 
22580 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74  or "memory". Att
22590 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69  empting to set i
225a0 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76  t to any other v
225b0 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61  alue is.**     a
225c0 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20  n error)^. .**  
225d0 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73     ^If "ro" is s
225e0 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74  pecified, then t
225f0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
22600 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f  pened for read-o
22610 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  nly .**     acce
22620 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74  ss, just as if t
22630 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
22640 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68  READONLY] flag h
22650 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74  ad been set in t
22660 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64  he .**     third
22670 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
22680 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
22690 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
226a0 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a  ion is set to .*
226b0 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e  *     "rw", then
226c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
226d0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
226e0 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20  -write (but not 
226f0 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20  create) .**     
22700 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51  access, as if SQ
22710 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
22720 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c  ITE (but not SQL
22730 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29  ITE_OPEN_CREATE)
22740 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65   had .**     bee
22750 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72  n set. ^Value "r
22760 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  wc" is equivalen
22770 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74  t to setting bot
22780 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  h .**     SQLITE
22790 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
227a0 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  and SQLITE_OPEN_
227b0 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65  CREATE.  ^If the
227c0 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a   mode option is.
227d0 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d  **     set to "m
227e0 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75  emory" then a pu
227f0 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  re [in-memory da
22800 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76  tabase] that nev
22810 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20  er reads.**     
22820 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64  or writes from d
22830 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74  isk is used. ^It
22840 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20   is an error to 
22850 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20  specify a value 
22860 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d  for.**     the m
22870 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  ode parameter th
22880 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72  at is less restr
22890 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74  ictive than that
228a0 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
228b0 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70       the flags p
228c0 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69  assed in the thi
228d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
228e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
228f0 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
22900 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54  <b>cache</b>: ^T
22910 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
22920 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
22930 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22   either "shared"
22940 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76   or.**     "priv
22950 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69  ate". ^Setting i
22960 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73  t to "shared" is
22970 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
22980 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  etting the.**   
22990 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48    SQLITE_OPEN_SH
229a0 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e  AREDCACHE bit in
229b0 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
229c0 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a  ent passed to.**
229d0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65       sqlite3_ope
229e0 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67  n_v2(). ^Setting
229f0 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d   the cache param
22a00 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65  eter to "private
22a10 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75  " is .**     equ
22a20 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
22a30 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  ng the SQLITE_OP
22a40 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
22a50 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20  bit..**     ^If 
22a60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22a70 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
22a80 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65  e "cache" parame
22a90 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69  ter is present i
22aa0 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66  n.**     a URI f
22ab0 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c  ilename, its val
22ac0 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79  ue overrides any
22ad0 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73   behavior reques
22ae0 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a  ted by setting.*
22af0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
22b00 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f  N_PRIVATECACHE o
22b10 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  r SQLITE_OPEN_SH
22b20 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a  AREDCACHE flag..
22b30 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70  **.**  <li> <b>p
22b40 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73  sow</b>: ^The ps
22b50 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64  ow parameter ind
22b60 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f  icates whether o
22b70 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20  r not the.**    
22b80 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72   [powersafe over
22b90 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20  write] property 
22ba0 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74  does or does not
22bb0 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a   apply to the.**
22bc0 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64       storage med
22bd0 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20  ia on which the 
22be0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65  database file re
22bf0 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  sides..**.**  <l
22c00 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e  i> <b>nolock</b>
22c10 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61  : ^The nolock pa
22c20 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
22c30 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d  lean query param
22c40 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63  eter.**     whic
22c50 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65  h if set disable
22c60 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69  s file locking i
22c70 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e  n rollback journ
22c80 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a  al modes.  This.
22c90 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c  **     is useful
22ca0 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61   for accessing a
22cb0 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66   database on a f
22cc0 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64  ilesystem that d
22cd0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73  oes not.**     s
22ce0 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20  upport locking. 
22cf0 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62   Caution:  Datab
22d00 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d  ase corruption m
22d10 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74  ight result if t
22d20 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72  wo.**     or mor
22d30 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74  e processes writ
22d40 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  e to the same da
22d50 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f  tabase and any o
22d60 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20  ne of those.**  
22d70 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65     processes use
22d80 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a  s nolock=1..**.*
22d90 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74  *  <li> <b>immut
22da0 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69  able</b>: ^The i
22db0 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74  mmutable paramet
22dc0 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
22dd0 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72  query.**     par
22de0 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69  ameter that indi
22df0 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64  cates that the d
22e00 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
22e10 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20  stored on.**    
22e20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
22e30 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62  .  ^When immutab
22e40 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74  le is set, SQLit
22e50 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
22e60 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61  he.**     databa
22e70 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62  se file cannot b
22e80 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20  e changed, even 
22e90 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74  by a process wit
22ea0 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20  h higher.**     
22eb0 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73  privilege, and s
22ec0 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  o the database i
22ed0 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e  s opened read-on
22ee0 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69  ly and all locki
22ef0 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68  ng.**     and ch
22f00 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69  ange detection i
22f10 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75  s disabled.  Cau
22f20 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68  tion: Setting th
22f30 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20  e immutable.**  
22f40 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61     property on a
22f50 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
22f60 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74  hat does in fact
22f70 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75   change can resu
22f80 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63  lt.**     in inc
22f90 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73  orrect query res
22fa0 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  ults and/or [SQL
22fb0 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72  ITE_CORRUPT] err
22fc0 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20  ors..**     See 
22fd0 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
22fe0 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a  CAP_IMMUTABLE]..
22ff0 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75  **       .** </u
23000 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66  l>.**.** ^Specif
23010 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20  ying an unknown 
23020 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
23030 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
23040 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74   of a URI is not
23050 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46   an.** error.  F
23060 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
23070 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75  f SQLite might u
23080 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69  nderstand additi
23090 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61  onal query.** pa
230a0 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22  rameters.  See "
230b0 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72  [query parameter
230c0 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d  s with special m
230d0 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65  eaning to SQLite
230e0 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  ]" for.** additi
230f0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
23100 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
23110 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d  lename examples]
23120 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61  ] <h3>URI filena
23130 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e  me examples</h3>
23140 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  .**.** <table bo
23150 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63  rder="1" align=c
23160 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e  enter cellpaddin
23170 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  g=5>.** <tr><th>
23180 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c   URI filenames <
23190 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c  th> Results.** <
231a0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
231b0 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
231c0 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
231d0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
231e0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
231f0 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e  rectory..** <tr>
23200 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
23210 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e  fred/data.db<br>
23220 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
23230 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  e:///home/fred/d
23240 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20  ata.db <br> .** 
23250 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
23260 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66  localhost/home/f
23270 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
23280 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
23290 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61     Open the data
232a0 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65  base file "/home
232b0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a  /fred/data.db"..
232c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
232d0 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65  ://darkstar/home
232e0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74  /fred/data.db <t
232f0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
23300 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73  An error. "darks
23310 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65  tar" is not a re
23320 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69  cognized authori
23330 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73  ty..** <tr><td s
23340 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63  tyle="white-spac
23350 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20  e:nowrap"> .**  
23360 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
23370 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61  C:/Documents%20a
23380 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72  nd%20Settings/fr
23390 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e  ed/Desktop/data.
233a0 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57  db.**     <td> W
233b0 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65  indows only: Ope
233c0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
233d0 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64  .db" on fred's d
233e0 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a  esktop on drive.
233f0 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20  **          C:. 
23400 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32  Note that the %2
23410 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68  0 escaping in th
23420 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f  is example is no
23430 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20  t strictly .**  
23440 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72          necessar
23450 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63  y - space charac
23460 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  ters can be used
23470 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20   literally.**   
23480 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69         in URI fi
23490 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e  lenames..** <tr>
234a0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
234b0 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d  b?mode=ro&cache=
234c0 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a  private <td> .**
234d0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
234e0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
234f0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
23500 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d  ectory for read-
23510 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20  only access..** 
23520 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c           Regardl
23530 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
23540 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63  r not shared-cac
23550 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  he mode is enabl
23560 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
23570 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61    default, use a
23580 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a   private cache..
23590 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
235a0 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
235b0 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74  .db?vfs=unix-dot
235c0 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  file <td>.**    
235d0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
235e0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
235f0 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
23600 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
23610 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20  dotfile".**     
23620 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64       that uses d
23630 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63  ot-files in plac
23640 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73  e of posix advis
23650 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20  ory locking..** 
23660 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
23670 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
23680 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
23690 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
236a0 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
236b0 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
236c0 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
236d0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
236e0 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
236f0 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
23700 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
23710 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
23720 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
23730 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
23740 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
23750 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
23760 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
23770 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
23780 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
23790 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
237a0 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
237b0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
237c0 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
237d0 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
237e0 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
237f0 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
23800 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
23810 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
23820 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
23830 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
23840 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
23850 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
23860 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
23870 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
23880 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
23890 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
238a0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
238b0 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
238c0 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
238d0 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
238e0 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
238f0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
23900 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
23910 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
23920 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
23930 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
23940 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
23950 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
23960 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
23970 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
23980 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
23990 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
239a0 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
239b0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
239c0 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
239d0 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
239e0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
239f0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
23a00 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
23a10 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
23a20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
23a30 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
23a40 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23a50 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
23a60 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  to Windows Runti
23a70 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  me users:</b>  T
23a80 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72  he temporary dir
23a90 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73  ectory must be s
23aa0 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  et.** prior to c
23ab0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f  alling sqlite3_o
23ac0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
23ad0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68  _open_v2().  Oth
23ae0 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a  erwise, various.
23af0 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74  ** features that
23b00 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65   require the use
23b10 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69   of temporary fi
23b20 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a  les may fail..**
23b30 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
23b40 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
23b50 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71  ctory].*/.int sq
23b60 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
23b70 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
23b80 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
23b90 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
23ba0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
23bb0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
23bc0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
23bd0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
23be0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
23bf0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
23c00 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
23c10 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
23c20 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
23c30 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
23c40 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
23c50 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
23c60 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
23c70 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
23c80 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
23c90 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
23ca0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
23cb0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
23cc0 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
23cd0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
23ce0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
23cf0 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
23d00 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
23d10 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
23d20 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
23d30 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
23d40 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
23d50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23d60 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f  Obtain Values Fo
23d70 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73  r URI Parameters
23d80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
23d90 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65   utility routine
23da0 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  s, useful to VFS
23db0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
23dc0 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20  , that check.** 
23dd0 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61  to see if a data
23de0 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20  base file was a 
23df0 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  URI that contain
23e00 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75  ed a specific qu
23e10 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ery .** paramete
23e20 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74  r, and if so obt
23e30 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  ains the value o
23e40 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72  f that query par
23e50 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
23e60 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61   F is the databa
23e70 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  se filename poin
23e80 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
23e90 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68  the xOpen() meth
23ea0 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20  od of .** a VFS 
23eb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
23ec0 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61  hen the flags pa
23ed0 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
23ee0 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a  () has one or .*
23ef0 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
23f00 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
23f10 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
23f20 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65  MAIN_DB] bits se
23f30 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68  t and.** P is th
23f40 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75  e name of the qu
23f50 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ery parameter, t
23f60 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  hen.** sqlite3_u
23f70 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
23f80 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  ) returns the va
23f90 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20  lue of the P.** 
23fa0 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20  parameter if it 
23fb0 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c  exists or a NULL
23fc0 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f   pointer if P do
23fd0 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73  es not appear as
23fe0 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   a .** query par
23ff0 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66  ameter on F.  If
24000 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61   P is a query pa
24010 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20  rameter of F.** 
24020 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20  has no explicit 
24030 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69  value, then sqli
24040 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
24050 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a  r(F,P) returns.*
24060 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
24070 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
24080 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
24090 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
240a0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73  P,B) routine ass
240b0 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61  umes that P is a
240c0 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61   boolean.** para
240d0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
240e0 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61  s true (1) or fa
240f0 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e  lse (0) accordin
24100 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a  g to the value.*
24110 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c  * of P.  The sql
24120 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
24130 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
24140 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
24150 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65   if the.** value
24160 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65   of query parame
24170 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
24180 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f  "yes", "true", o
24190 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a  r "on" in any.**
241a0 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20   case or if the 
241b0 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
241c0 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d  h a non-zero num
241d0 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71  ber.  The .** sq
241e0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
241f0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
24200 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  s returns false 
24210 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65  (0) if the value
24220 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   of.** query par
24230 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
24240 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22  of "no", "false"
24250 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e  , or "off" in an
24260 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20  y case or.** if 
24270 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
24280 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20   with a numeric 
24290 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e  zero.  If P is n
242a0 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61  ot a query.** pa
242b0 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20  rameter on F or 
242c0 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  if the value of 
242d0 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61  P is does not ma
242e0 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a  tch any of the.*
242f0 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71  * above, then sq
24300 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
24310 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
24320 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54   (B!=0)..**.** T
24330 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  he sqlite3_uri_i
24340 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74  nt64(F,P,D) rout
24350 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ine converts the
24360 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f   value of P into
24370 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67   a.** 64-bit sig
24380 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
24390 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74  returns that int
243a0 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20  eger, or D if P 
243b0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73  does not.** exis
243c0 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65  t.  If the value
243d0 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69   of P is somethi
243e0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e  ng other than an
243f0 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a   integer, then.*
24400 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  * zero is return
24410 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20  ed..** .** If F 
24420 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
24430 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
24440 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
24450 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  P) returns NULL 
24460 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
24470 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24480 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66  ) returns B.  If
24490 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c   F is not a NULL
244a0 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20   pointer and.** 
244b0 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
244c0 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  e file pathname 
244d0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
244e0 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ite passed into 
244f0 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53  the xOpen.** VFS
24500 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
24510 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
24520 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e  is routine is un
24530 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
24540 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61  ably.** undesira
24550 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ble..*/.const ch
24560 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f  ar *sqlite3_uri_
24570 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
24580 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
24590 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
245a0 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ram);.int sqlite
245b0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f  3_uri_boolean(co
245c0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
245d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
245e0 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c  ram, int bDefaul
245f0 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  t);.sqlite3_int6
24600 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  4 sqlite3_uri_in
24610 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t64(const char*,
24620 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
24630 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a  lite3_int64);...
24640 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24650 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
24660 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e  Messages.**.** ^
24670 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
24680 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
24690 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
246a0 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
246b0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
246c0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
246d0 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
246e0 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
246f0 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
24700 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
24710 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
24720 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
24730 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
24740 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
24750 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
24760 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
24770 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
24780 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
24790 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
247a0 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71  efined.  ^The sq
247b0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
247c0 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
247d0 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
247e0 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
247f0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
24800 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
24810 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
24820 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
24830 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
24840 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
24850 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
24860 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
24870 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
24880 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
24890 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
248a0 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
248b0 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
248c0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
248d0 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
248e0 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
248f0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
24900 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
24910 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
24920 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
24930 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
24940 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
24950 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
24960 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
24970 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
24980 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
24990 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
249a0 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
249b0 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
249c0 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
249d0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
249e0 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
249f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
24a00 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63  rrstr() interfac
24a10 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e  e returns the En
24a20 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
24a30 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63  ext.** that desc
24a40 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c  ribes the [resul
24a50 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d  t code], as UTF-
24a60 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  8..** ^(Memory t
24a70 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
24a80 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
24a90 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
24aa0 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73  nally.** and mus
24ab0 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62  t not be freed b
24ac0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
24ad0 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  n)^..**.** When 
24ae0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
24af0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
24b00 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
24b10 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
24b20 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
24b30 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
24b40 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
24b50 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
24b60 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
24b70 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
24b80 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
24b90 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
24ba0 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
24bb0 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
24bc0 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
24bd0 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
24be0 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
24bf0 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
24c00 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
24c10 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
24c20 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
24c30 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
24c40 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
24c50 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
24c60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
24c70 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
24c80 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
24c90 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
24ca0 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
24cb0 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
24cc0 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
24cd0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
24ce0 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
24cf0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
24d00 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
24d10 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
24d20 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
24d30 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
24d40 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
24d50 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
24d60 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
24d70 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
24d80 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
24d90 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
24da0 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
24db0 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
24dc0 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
24dd0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
24de0 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
24df0 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
24e00 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
24e10 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
24e20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
24e30 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
24e40 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
24e50 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
24e60 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
24e70 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
24e80 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
24e90 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
24ea0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
24eb0 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
24ec0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
24ed0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
24ee0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
24ef0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24f00 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
24f10 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
24f20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
24f30 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
24f40 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
24f50 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
24f60 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
24f70 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
24f80 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
24f90 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
24fa0 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
24fb0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
24fc0 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
24fd0 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
24fe0 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
24ff0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
25000 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
25010 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
25020 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
25030 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
25040 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25050 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
25060 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
25070 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
25080 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
25090 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
250a0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
250b0 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
250c0 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
250d0 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
250e0 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
250f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
25100 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
25110 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
25120 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
25130 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
25140 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
25150 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
25160 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
25170 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
25180 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
25190 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
251a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
251b0 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
251c0 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
251d0 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
251e0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
251f0 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
25200 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
25210 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
25220 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
25230 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
25240 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
25250 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
25260 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
25270 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
25280 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
25290 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
252a0 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
252b0 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
252c0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
252d0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
252e0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
252f0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
25300 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
25310 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
25320 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
25330 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
25340 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
25350 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
25360 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
25370 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
25380 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
25390 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
253a0 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
253b0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
253c0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
253d0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
253e0 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
253f0 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
25400 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
25410 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
25420 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
25430 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
25440 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
25450 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
25460 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
25470 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
25480 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
25490 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
254a0 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
254b0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
254c0 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
254d0 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
254e0 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
254f0 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
25500 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
25510 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
25520 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
25530 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
25540 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
25550 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
25560 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
25570 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
25580 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
25590 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
255a0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
255b0 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
255c0 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
255d0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
255e0 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
255f0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
25600 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
25610 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
25620 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
25630 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
25640 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
25650 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
25660 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
25670 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
25680 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
25690 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
256a0 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
256b0 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
256c0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
256d0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
256e0 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
256f0 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
25700 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
25710 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
25720 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
25730 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
25740 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
25750 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
25760 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
25770 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
25780 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
25790 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
257a0 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
257b0 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
257c0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
257d0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
257e0 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
257f0 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
25800 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
25810 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
25820 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
25830 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
25840 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
25850 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
25860 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
25870 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
25880 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
25890 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
258a0 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
258b0 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
258c0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
258d0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
258e0 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
258f0 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
25900 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
25910 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
25920 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
25930 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
25940 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
25950 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
25960 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
25970 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
25980 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
25990 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
259a0 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
259b0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
259c0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
259d0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
259e0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
259f0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
25a00 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
25a10 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
25a20 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
25a30 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
25a40 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
25a50 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
25a60 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
25a70 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
25a80 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
25a90 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
25aa0 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
25ab0 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
25ac0 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
25ad0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
25ae0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
25af0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
25b00 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
25b10 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
25b20 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
25b30 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
25b40 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
25b50 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
25b60 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
25b70 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
25b80 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
25b90 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
25ba0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25bb0 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
25bc0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
25bd0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
25be0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
25bf0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
25c00 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
25c10 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
25c20 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25c30 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
25c40 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
25c50 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
25c60 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
25c70 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
25c80 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
25c90 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
25ca0 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
25cb0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25cc0 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
25cd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
25ce0 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
25cf0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
25d00 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
25d10 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
25d20 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
25d30 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
25d40 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
25d50 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
25d60 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
25d70 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
25d80 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
25d90 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
25da0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25db0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
25dc0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
25dd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
25de0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
25df0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
25e00 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
25e10 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
25e20 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
25e30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25e40 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
25e50 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
25e60 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
25e70 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
25e80 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25e90 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
25ea0 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
25eb0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
25ec0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
25ed0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
25ee0 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
25ef0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
25f00 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
25f10 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
25f20 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
25f30 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
25f40 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
25f50 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
25f60 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
25f70 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
25f80 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
25f90 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
25fa0 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
25fb0 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
25fc0 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
25fd0 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
25fe0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
25ff0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
26000 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
26010 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
26020 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
26030 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26040 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
26050 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
26060 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
26070 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26080 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
26090 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
260a0 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
260b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
260c0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
260d0 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
260e0 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
260f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26100 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
26110 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
26120 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26130 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
26140 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
26150 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
26160 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
26170 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
26180 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
26190 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
261a0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
261b0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
261c0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
261d0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
261e0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
261f0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
26200 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
26210 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
26220 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
26230 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
26240 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
26250 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
26260 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
26270 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
26280 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
26290 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
262a0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
262b0 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
262c0 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ers.</dd>)^.**.*
262d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
262e0 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d  _WORKER_THREADS]
262f0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26300 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
26310 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ADS</dt>.** <dd>
26320 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
26330 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20  er of auxiliary 
26340 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74  worker threads t
26350 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20  hat a single.** 
26360 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26370 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c  ent] may start.<
26380 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
26390 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
263a0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
263b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
263c0 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
263d0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
263e0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
263f0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
26400 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
26410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26420 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
26430 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
26440 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
26450 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
26460 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
26470 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
26480 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
26490 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
264a0 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
264b0 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
264c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
264d0 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
264e0 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
264f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
26500 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
26510 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
26520 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26530 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
26540 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
26550 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26560 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
26570 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
26580 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26590 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
265a0 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
265b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
265c0 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
265d0 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a  S           11..
265e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
265f0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
26600 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
26610 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
26620 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
26630 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
26640 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
26650 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
26660 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
26670 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
26680 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
26690 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
266a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
266b0 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
266c0 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
266d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
266e0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
266f0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
26700 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
26710 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
26720 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
26730 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
26740 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
26750 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26760 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
26770 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
26780 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
26790 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
267a0 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
267b0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
267c0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
267d0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
267e0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
267f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
26800 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
26810 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
26820 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
26830 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
26840 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
26850 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
26860 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
26870 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
26880 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
26890 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
268a0 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
268b0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
268c0 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
268d0 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
268e0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
268f0 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
26900 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
26910 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
26920 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
26930 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e  ^When nByte is n
26940 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
26950 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
26960 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
26970 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
26980 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
26990 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
269a0 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
269b0 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
269c0 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
269d0 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
269e0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
269f0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
26a00 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
26a10 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
26a20 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
26a30 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
26a40 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
26a50 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
26a60 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
26a70 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
26a80 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
26a90 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
26aa0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
26ab0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
26ac0 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74  nator bytes as t
26ad0 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65  his saves SQLite
26ae0 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a   from having to.
26af0 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f  ** make a copy o
26b00 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
26b10 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  ng..**.** ^If pz
26b20 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
26b30 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
26b40 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
26b50 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
26b60 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
26b70 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
26b80 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
26b90 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
26ba0 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
26bb0 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
26bc0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
26bd0 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
26be0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
26bf0 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
26c00 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
26c10 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
26c20 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
26c30 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
26c40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26c50 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
26c60 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
26c70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
26c80 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
26c90 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
26ca0 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
26cb0 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
26cc0 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
26cd0 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
26ce0 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
26cf0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
26d00 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
26d10 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
26d20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
26d30 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
26d40 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
26d50 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
26d60 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
26d70 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
26d80 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
26d90 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
26da0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
26db0 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
26dc0 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
26dd0 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
26de0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
26df0 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
26e00 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
26e10 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
26e20 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
26e30 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
26e40 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
26e50 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
26e60 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
26e70 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
26e80 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
26e90 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
26ea0 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
26eb0 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
26ec0 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
26ed0 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
26ee0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
26ef0 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
26f00 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
26f10 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
26f20 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
26f30 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
26f40 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
26f50 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
26f60 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
26f70 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
26f80 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
26f90 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
26fa0 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
26fb0 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
26fc0 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
26fd0 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
26fe0 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
26ff0 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
27000 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
27010 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
27020 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
27030 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
27040 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
27050 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
27060 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
27070 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
27080 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
27090 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
270a0 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
270b0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
270c0 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
270d0 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c   As many as [SQL
270e0 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52  ITE_MAX_SCHEMA_R
270f0 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73  ETRY].** retries
27100 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f   will occur befo
27110 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  re sqlite3_step(
27120 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72  ) gives up and r
27130 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e  eturns an error.
27140 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
27150 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
27160 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
27170 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27180 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
27190 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
271a0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
271b0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
271c0 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
271d0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
271e0 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
271f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
27200 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
27210 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
27220 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
27230 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
27240 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
27250 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
27260 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
27270 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27280 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
27290 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
272a0 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
272b0 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
272c0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
272d0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
272e0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
272f0 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
27300 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
27310 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
27320 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
27330 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
27340 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
27350 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
27360 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
27370 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
27380 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
27390 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
273a0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
273b0 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
273c0 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
273d0 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
273e0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
273f0 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
27400 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
27410 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
27420 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
27430 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
27440 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
27450 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
27460 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
27470 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
27480 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
27490 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
274a0 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
274b0 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
274c0 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
274d0 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
274e0 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
274f0 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
27500 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
27510 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
27520 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
27530 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
27540 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
27550 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
27560 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
27570 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
27580 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
27590 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d  NABLE_STAT3] com
275a0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
275b0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
275c0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
275d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
275e0 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
275f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
27600 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
27610 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
27620 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
27630 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
27640 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
27650 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
27660 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
27670 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
27680 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
27690 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
276a0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
276b0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
276c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
276d0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
276e0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
276f0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
27700 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
27710 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
27720 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
27730 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
27740 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
27750 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
27760 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
27770 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
27780 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
27790 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
277a0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
277b0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
277c0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
277d0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
277e0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
277f0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
27800 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
27810 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
27820 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
27830 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
27840 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
27850 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
27860 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27870 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
27880 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
27890 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
278a0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
278b0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
278c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
278d0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
278e0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
278f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
27900 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
27910 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
27920 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
27930 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
27940 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
27950 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
27960 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
27970 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
27980 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
27990 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
279a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
279b0 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
279c0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
279d0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
279e0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
279f0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
27a00 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
27a10 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
27a20 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
27a30 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
27a40 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
27a50 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
27a60 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
27a70 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
27a80 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
27a90 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
27aa0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
27ab0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
27ac0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
27ad0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
27ae0 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
27af0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
27b00 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
27b10 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  SQL.**.** ^This 
27b20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
27b30 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
27b40 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
27b50 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
27b60 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
27b70 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
27b80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27b90 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
27ba0 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
27bb0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
27bc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27bd0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
27be0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
27bf0 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
27c00 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
27c10 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
27c20 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
27c30 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
27c40 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
27c50 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
27c60 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54  atabase.**.** ^T
27c70 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
27c80 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
27c90 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
27ca0 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
27cb0 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
27cc0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
27cd0 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
27ce0 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
27cf0 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
27d00 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
27d10 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
27d20 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
27d30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
27d40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
27d50 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
27d60 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
27d70 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
27d80 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
27d90 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
27da0 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
27db0 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
27dc0 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
27dd0 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
27de0 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
27df0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
27e00 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
27e10 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
27e20 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
27e30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27e40 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
27e50 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
27e60 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
27e70 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
27e80 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
27e90 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
27ea0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
27eb0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
27ec0 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
27ed0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
27ee0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
27ef0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
27f00 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
27f10 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
27f20 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
27f30 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
27f40 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
27f50 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
27f60 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
27f70 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
27f80 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
27f90 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
27fa0 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
27fb0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
27fc0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
27fd0 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
27fe0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
27ff0 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
28000 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
28010 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
28020 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
28030 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
28040 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
28050 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
28060 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
28070 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
28080 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
28090 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
280a0 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
280b0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
280c0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
280d0 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
280e0 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
280f0 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
28100 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
28110 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
28120 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
28130 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
28140 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
28150 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
28160 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
28170 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  k..*/.int sqlite
28180 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
28190 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
281a0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
281b0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
281c0 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
281d0 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
281e0 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  n Reset.**.** ^T
281f0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
28200 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
28210 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
28220 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
28230 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
28240 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
28250 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
28260 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
28270 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
28280 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f  p(S)] but has no
28290 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  t run to complet
282a0 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e  ion and/or has n
282b0 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65  ot .** been rese
282c0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
282d0 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68  _reset(S)].  ^Th
282e0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
282f0 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66  usy(S).** interf
28300 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
28310 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c  e if S is a NULL
28320 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20   pointer.  If S 
28330 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c  is not a .** NUL
28340 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73  L pointer and is
28350 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74   not a pointer t
28360 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61  o a valid [prepa
28370 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
28380 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74  * object, then t
28390 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
283a0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
283b0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
283c0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
283d0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
283e0 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69  sed in combinati
283f0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  on [sqlite3_next
28400 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c  _stmt()].** to l
28410 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72  ocate all prepar
28420 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
28430 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
28440 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e  database .** con
28450 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65  nection that are
28460 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e   in need of bein
28470 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63  g reset.  This c
28480 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66  an be used,.** f
28490 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64  or example, in d
284a0 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e  iagnostic routin
284b0 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72  es to search for
284c0 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74   prepared .** st
284d0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  atements that ar
284e0 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e  e holding a tran
284f0 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f  saction open..*/
28500 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
28510 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73  t_busy(sqlite3_s
28520 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
28530 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
28540 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
28550 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
28560 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
28570 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
28580 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
28590 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
285a0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
285b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
285c0 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
285d0 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
285e0 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
285f0 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
28600 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
28610 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
28620 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
28630 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
28640 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
28650 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
28660 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
28670 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
28680 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
28690 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
286a0 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
286b0 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
286c0 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
286d0 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
286e0 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
286f0 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
28700 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
28710 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
28720 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
28730 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
28740 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
28750 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
28760 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
28770 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28780 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
28790 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
287a0 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
287b0 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
287c0 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
287d0 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
287e0 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
287f0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
28800 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
28810 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
28820 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
28830 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
28840 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
28850 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
28860 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
28870 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
28880 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
28890 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
288a0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
288b0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
288c0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
288d0 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
288e0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
288f0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
28900 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
28910 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
28920 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
28930 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
28940 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
28950 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
28960 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
28970 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
28980 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
28990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
289a0 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
289b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
289c0 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
289d0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
289e0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
289f0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
28a00 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
28a10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28a20 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
28a30 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
28a40 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
28a50 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
28a60 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
28a70 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
28a80 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
28a90 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
28aa0 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
28ab0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
28ac0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
28ad0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
28ae0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
28af0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
28b00 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
28b10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
28b20 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28b30 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
28b40 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
28b50 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
28b60 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
28b70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
28b80 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
28b90 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
28ba0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
28bb0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
28bc0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
28bd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
28be0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
28bf0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
28c00 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28c10 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
28c20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
28c30 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
28c40 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
28c50 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
28c60 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
28c70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
28c80 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
28c90 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
28ca0 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
28cb0 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
28cc0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28cd0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
28ce0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
28cf0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
28d00 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
28d10 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
28d20 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
28d30 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
28d40 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
28d50 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
28d60 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
28d70 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
28d80 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
28d90 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
28da0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
28db0 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
28dc0 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
28dd0 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
28de0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
28df0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
28e00 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
28e10 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
28e20 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
28e30 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
28e40 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
28e50 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
28e60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
28e70 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
28e80 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
28e90 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
28ea0 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
28eb0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
28ec0 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
28ed0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
28ee0 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
28ef0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
28f00 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
28f10 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
28f20 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
28f30 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
28f40 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
28f50 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
28f60 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
28f70 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
28f80 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
28f90 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
28fa0 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
28fb0 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
28fc0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
28fd0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
28fe0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
28ff0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
29000 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
29010 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ding}.**.** ^(In
29020 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
29030 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
29040 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29050 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
29060 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
29070 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
29080 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
29090 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
290a0 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
290b0 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
290c0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
290d0 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
290e0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
290f0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
29100 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
29110 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
29120 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
29130 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
29140 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
29150 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
29160 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
29170 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
29180 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
29190 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
291a0 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
291b0 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
291c0 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
291d0 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
291e0 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
291f0 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
29200 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
29210 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
29220 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
29230 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
29240 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
29250 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
29260 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
29270 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
29280 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
29290 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
292a0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
292b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
292c0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
292d0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
292e0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
292f0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
29300 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
29310 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
29320 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
29330 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
29340 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
29350 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
29360 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
29370 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
29380 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
29390 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
293a0 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
293b0 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
293c0 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
293d0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
293e0 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
293f0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
29400 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
29410 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
29420 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
29430 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
29440 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
29450 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
29460 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
29470 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
29480 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
29490 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
294a0 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
294b0 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
294c0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
294d0 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
294e0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
294f0 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
29500 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
29510 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
29520 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
29530 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
29540 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
29550 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
29560 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
29570 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
29580 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
29590 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
295a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
295b0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
295c0 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
295d0 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
295e0 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
295f0 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
29600 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
29610 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
29620 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
29630 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
29640 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
29650 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
29660 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
29670 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
29680 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
29690 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
296a0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
296b0 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
296c0 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
296d0 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
296e0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
296f0 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
29700 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
29710 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
29720 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
29730 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
29740 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
29750 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
29760 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
29770 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
29780 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
29790 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
297a0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
297b0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
297c0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
297d0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
297e0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
297f0 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
29800 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
29810 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
29820 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
29830 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
29840 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
29850 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
29860 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
29870 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
29880 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a  d_text64() then.
29890 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  ** that paramete
298a0 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
298b0 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
298c0 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
298d0 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
298e0 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
298f0 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
29900 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
29910 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
29920 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
29930 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
29940 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
29950 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
29960 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
29970 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
29980 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
29990 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
299a0 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
299b0 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
299c0 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
299d0 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
299e0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
299f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
29a00 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
29a10 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42  ment to the BLOB
29a20 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64   and string bind
29a30 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ing interfaces.*
29a40 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  * is a destructo
29a50 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
29a60 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
29a70 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
29a80 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
29a90 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
29aa0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
29ab0 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
29ac0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
29ad0 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
29ae0 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
29af0 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e   bind API fails.
29b00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
29b10 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
29b20 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
29b30 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
29b40 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
29b50 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
29b60 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
29b70 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
29b80 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
29b90 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
29ba0 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
29bb0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
29bc0 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
29bd0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
29be0 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
29bf0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
29c00 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
29c10 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
29c20 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
29c30 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
29c40 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
29c50 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
29c60 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67  * ^The sixth arg
29c70 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
29c80 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d  _bind_text64() m
29c90 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a  ust be one of.**
29ca0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
29cb0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
29cc0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
29cd0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
29ce0 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63  16LE].** to spec
29cf0 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ify the encoding
29d00 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20   of the text in 
29d10 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
29d20 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ter.  If.** the 
29d30 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
29d40 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
29d50 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f  ext64() is not o
29d60 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c  ne of the.** all
29d70 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77  owed values show
29d80 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74  n above, or if t
29d90 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
29da0 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a   is different.**
29db0 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69   from the encodi
29dc0 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ng specified by 
29dd0 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65  the sixth parame
29de0 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ter, then the be
29df0 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
29e00 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
29e10 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29e20 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
29e30 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
29e40 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
29e50 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
29e60 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
29e70 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
29e80 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
29e90 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
29ea0 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
29eb0 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
29ec0 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
29ed0 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
29ee0 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
29ef0 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
29f00 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
29f10 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
29f20 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
29f30 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
29f40 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
29f50 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
29f60 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
29f70 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
29f80 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
29f90 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
29fa0 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
29fb0 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
29fc0 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
29fd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
29fe0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
29ff0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
2a000 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
2a010 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2a020 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
2a030 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2a040 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
2a050 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2a060 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
2a070 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
2a080 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
2a090 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
2a0a0 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
2a0b0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
2a0c0 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
2a0d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
2a0e0 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
2a0f0 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
2a100 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2a110 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2a120 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
2a130 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
2a140 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
2a150 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
2a160 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
2a170 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
2a180 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
2a190 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
2a1a0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
2a1b0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
2a1c0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
2a1d0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2a1e0 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
2a1f0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
2a200 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
2a210 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
2a220 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
2a230 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
2a240 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74  TE_TOOBIG] might
2a250 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
2a260 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74  the size of a st
2a270 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20  ring or BLOB.** 
2a280 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69  exceeds limits i
2a290 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  mposed by [sqlit
2a2a0 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2a2b0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29  E_LIMIT_LENGTH])
2a2c0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d   or.** [SQLITE_M
2a2d0 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e  AX_LENGTH]..** ^
2a2e0 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
2a2f0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
2a300 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
2a310 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2a320 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
2a330 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
2a340 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
2a350 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
2a360 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2a370 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2a380 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
2a390 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a3a0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
2a3b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2a3c0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2a3d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2a3e0 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
2a3f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2a400 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
2a410 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
2a420 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2a430 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69  bind_blob64(sqli
2a440 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2a450 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c  const void*, sql
2a460 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
2a470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a480 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
2a490 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2a4a0 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
2a4b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a4c0 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
2a4d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
2a4e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a4f0 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
2a500 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
2a510 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a520 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
2a530 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
2a540 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
2a550 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2a560 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a570 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2a580 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  mt*,int,const ch
2a590 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28  ar*,int,void(*)(
2a5a0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2a5b0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2a5c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a5d0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2a5e0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2a5f0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2a600 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2a610 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a620 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
2a630 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2a640 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2a650 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2a660 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e  )(void*), unsign
2a670 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67  ed char encoding
2a680 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2a690 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
2a6a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2a6b0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
2a6c0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2a6d0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
2a6e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a6f0 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
2a700 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2a710 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
2a720 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ters.**.** ^This
2a730 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2a740 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
2a750 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
2a760 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
2a770 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2a780 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
2a790 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
2a7a0 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
2a7b0 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
2a7c0 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
2a7d0 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
2a7e0 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
2a7f0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
2a800 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
2a810 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2a820 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
2a830 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
2a840 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
2a850 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
2a860 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
2a870 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
2a880 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
2a890 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
2a8a0 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
2a8b0 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
2a8c0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
2a8d0 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
2a8e0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
2a8f0 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
2a900 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
2a910 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
2a920 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
2a930 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
2a940 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
2a950 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2a960 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2a970 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2a980 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a990 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2a9a0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2a9b0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a9c0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2a9d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2a9e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2a9f0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
2aa00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2aa10 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
2aa20 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a  t Parameter.**.*
2aa30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2aa40 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2aa50 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
2aa60 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
2aa70 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
2aa80 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
2aa90 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
2aaa0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2aab0 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
2aac0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2aad0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
2aae0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
2aaf0 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
2ab00 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
2ab10 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
2ab20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
2ab30 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
2ab40 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
2ab50 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
2ab60 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
2ab70 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
2ab80 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
2ab90 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
2aba0 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
2abb0 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
2abc0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
2abd0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
2abe0 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
2abf0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
2ac00 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
2ac10 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
2ac20 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
2ac30 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
2ac40 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
2ac50 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
2ac60 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
2ac70 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
2ac80 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
2ac90 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
2aca0 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
2acb0 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
2acc0 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
2acd0 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
2ace0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
2acf0 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
2ad00 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
2ad10 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
2ad20 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
2ad30 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
2ad40 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
2ad50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2ad60 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
2ad70 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2ad80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
2ad90 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2ada0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2adb0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2adc0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2add0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
2ade0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2adf0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2ae00 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
2ae10 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
2ae20 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2ae30 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2ae40 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
2ae50 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
2ae60 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
2ae70 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
2ae80 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2ae90 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
2aea0 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
2aeb0 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
2aec0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
2aed0 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
2aee0 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
2aef0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
2af00 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2af10 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2af20 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
2af30 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
2af40 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
2af50 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
2af60 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
2af70 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
2af80 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
2af90 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
2afa0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2afb0 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
2afc0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
2afd0 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
2afe0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2aff0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2b000 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2b010 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2b020 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2b030 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2b040 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2b050 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2b060 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2b070 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
2b080 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2b090 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
2b0a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
2b0b0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
2b0c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b0d0 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
2b0e0 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
2b0f0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
2b100 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
2b110 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
2b120 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
2b130 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
2b140 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
2b150 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2b160 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
2b170 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2b180 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
2b190 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
2b1a0 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
2b1b0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
2b1c0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
2b1d0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2b1e0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2b1f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b200 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
2b210 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
2b220 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  t Set.**.** ^Ret
2b230 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
2b240 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2b250 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
2b260 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
2b270 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b280 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
2b290 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2b2a0 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
2b2b0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
2b2c0 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
2b2d0 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
2b2e0 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
2b2f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2b300 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
2b310 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
2b320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2b330 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2b340 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2b350 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
2b360 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
2b370 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
2b380 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2b390 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
2b3a0 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
2b3b0 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
2b3c0 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
2b3d0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2b3e0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
2b3f0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2b400 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
2b410 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2b420 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2b430 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2b440 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
2b450 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b460 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
2b470 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2b480 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
2b490 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
2b4a0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
2b4b0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2b4c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b4d0 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
2b4e0 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
2b4f0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
2b500 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2b510 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
2b520 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
2b530 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2b540 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
2b550 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
2b560 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
2b570 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
2b580 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
2b590 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b5a0 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
2b5b0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
2b5c0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2b5d0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2b5e0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2b5f0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2b600 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2b610 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2b620 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2b630 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2b640 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
2b650 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2b660 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2b670 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2b680 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
2b690 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
2b6a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
2b6b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
2b6c0 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
2b6d0 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
2b6e0 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
2b6f0 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
2b700 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
2b710 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
2b720 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
2b730 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2b740 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2b750 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
2b760 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
2b770 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
2b780 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
2b790 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
2b7a0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
2b7b0 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
2b7c0 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
2b7d0 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
2b7e0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
2b7f0 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
2b800 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
2b810 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
2b820 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
2b830 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f   the next..*/.co
2b840 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2b850 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
2b860 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b870 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
2b880 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2b890 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2b8a0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
2b8b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2b8c0 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
2b8d0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2b8e0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2b8f0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
2b900 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
2b910 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
2b920 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
2b930 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
2b940 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
2b950 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
2b960 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
2b970 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
2b980 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
2b990 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
2b9a0 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
2b9b0 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
2b9c0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
2b9d0 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
2b9e0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2b9f0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
2ba00 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
2ba10 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
2ba20 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
2ba30 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2ba40 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
2ba50 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
2ba60 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
2ba70 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
2ba80 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
2ba90 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2baa0 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
2bab0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2bac0 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
2bad0 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2bae0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2baf0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2bb00 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2bb10 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2bb20 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2bb30 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2bb40 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2bb50 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2bb60 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2bb70 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
2bb80 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
2bb90 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
2bba0 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
2bbb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2bbc0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
2bbd0 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
2bbe0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
2bbf0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
2bc00 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
2bc10 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
2bc20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2bc30 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
2bc40 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
2bc50 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2bc60 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2bc70 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2bc80 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
2bc90 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
2bca0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
2bcb0 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
2bcc0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
2bcd0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
2bce0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
2bcf0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
2bd00 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
2bd10 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
2bd20 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
2bd30 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
2bd40 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
2bd50 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
2bd60 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
2bd70 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
2bd80 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
2bd90 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
2bda0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2bdb0 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
2bdc0 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
2bdd0 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
2bde0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
2bdf0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
2be00 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
2be10 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
2be20 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2be30 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
2be40 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
2be50 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
2be60 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
2be70 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
2be80 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
2be90 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
2bea0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
2beb0 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
2bec0 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
2bed0 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
2bee0 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
2bef0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
2bf00 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
2bf10 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
2bf20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
2bf30 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
2bf40 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
2bf50 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
2bf60 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
2bf70 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
2bf80 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
2bf90 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
2bfa0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2bfb0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2bfc0 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
2bfd0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
2bfe0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
2bff0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
2c000 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
2c010 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2c020 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
2c030 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2c040 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2c050 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2c060 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
2c070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2c080 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
2c090 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
2c0a0 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
2c0b0 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
2c0c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
2c0d0 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
2c0e0 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
2c0f0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2c100 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2c110 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
2c120 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2c130 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2c140 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2c150 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2c160 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2c170 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
2c180 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2c190 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
2c1a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c1b0 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
2c1c0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2c1d0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2c1e0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2c1f0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2c200 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2c210 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2c220 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2c230 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2c240 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2c250 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2c260 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
2c270 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2c280 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c290 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
2c2a0 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
2c2b0 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  Result.**.** ^(T
2c2c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2c2d0 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
2c2e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2c2f0 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
2c300 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
2c310 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2c320 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2c330 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
2c340 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
2c350 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
2c360 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
2c370 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
2c380 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2c390 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
2c3a0 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
2c3b0 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
2c3c0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
2c3d0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2c3e0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2c3f0 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
2c400 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2c410 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
2c420 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2c430 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
2c440 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2c450 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
2c460 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
2c470 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
2c480 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2c490 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
2c4a0 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
2c4b0 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
2c4c0 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
2c4d0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
2c4e0 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
2c4f0 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
2c500 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
2c510 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
2c520 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
2c530 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
2c540 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
2c550 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
2c560 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
2c570 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
2c580 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
2c590 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
2c5a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2c5b0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
2c5c0 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
2c5d0 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
2c5e0 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
2c5f0 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
2c600 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
2c610 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
2c620 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
2c630 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
2c640 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
2c650 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
2c660 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
2c670 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
2c680 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
2c690 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
2c6a0 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
2c6b0 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
2c6c0 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
2c6d0 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
2c6e0 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
2c6f0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
2c700 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
2c710 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2c720 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2c730 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
2c740 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2c750 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2c760 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
2c770 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2c780 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2c790 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
2c7a0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
2c7b0 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
2c7c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c7d0 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
2c7e0 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
2c7f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2c800 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2c810 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2c820 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2c830 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2c840 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
2c850 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
2c860 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c870 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
2c880 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
2c890 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
2c8a0 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
2c8b0 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
2c8c0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
2c8d0 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
2c8e0 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
2c8f0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
2c900 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
2c910 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
2c920 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
2c930 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
2c940 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
2c950 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
2c960 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2c970 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2c980 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2c990 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
2c9a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
2c9b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2c9c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2c9d0 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
2c9e0 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
2c9f0 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
2ca00 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2ca10 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
2ca20 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
2ca30 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2ca40 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
2ca50 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2ca60 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
2ca70 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2ca80 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2ca90 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
2caa0 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
2cab0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2cac0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
2cad0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2cae0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
2caf0 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
2cb00 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2cb10 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
2cb20 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
2cb30 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2cb40 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
2cb50 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2cb60 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
2cb70 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
2cb80 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
2cb90 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
2cba0 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
2cbb0 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
2cbc0 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
2cbd0 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
2cbe0 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
2cbf0 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
2cc00 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
2cc10 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
2cc20 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2cc30 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
2cc40 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
2cc50 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
2cc60 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2cc70 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
2cc80 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
2cc90 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
2cca0 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
2ccb0 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
2ccc0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
2ccd0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
2cce0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
2ccf0 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
2cd00 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
2cd10 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
2cd20 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
2cd30 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
2cd40 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2cd50 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2cd60 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
2cd70 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
2cd80 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
2cd90 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
2cda0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
2cdb0 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
2cdc0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
2cdd0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2cde0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
2cdf0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2ce00 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
2ce10 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
2ce20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
2ce30 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
2ce40 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
2ce50 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
2ce60 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
2ce70 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
2ce80 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
2ce90 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
2cea0 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
2ceb0 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
2cec0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2ced0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2cee0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
2cef0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
2cf00 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
2cf10 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2cf20 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
2cf30 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
2cf40 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
2cf50 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
2cf60 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
2cf70 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
2cf80 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2cf90 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2cfa0 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
2cfb0 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
2cfc0 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
2cfd0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2cfe0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
2cff0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
2d000 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
2d010 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2d020 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
2d030 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
2d040 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
2d050 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
2d060 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
2d070 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
2d080 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
2d090 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2d0a0 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
2d0b0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2d0c0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
2d0d0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2d0e0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
2d0f0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2d100 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
2d110 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
2d120 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
2d130 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
2d140 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2d150 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
2d160 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
2d170 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
2d180 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
2d190 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
2d1a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2d1b0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
2d1c0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
2d1d0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2d1e0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
2d1f0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
2d200 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
2d210 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
2d220 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2d230 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
2d240 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
2d250 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2d260 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2d270 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
2d280 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
2d290 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
2d2a0 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
2d2b0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
2d2c0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2d2d0 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
2d2e0 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
2d2f0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
2d300 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d310 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
2d320 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
2d330 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
2d340 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
2d350 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
2d360 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
2d370 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
2d380 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
2d390 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
2d3a0 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
2d3b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
2d3c0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
2d3d0 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
2d3e0 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
2d3f0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
2d400 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
2d410 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
2d420 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20  t after version 
2d430 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
2d440 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
2d450 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
2d460 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
2d470 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
2d480 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
2d490 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
2d4a0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2d4b0 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
2d4c0 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
2d4d0 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
2d4e0 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
2d4f0 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
2d500 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
2d510 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
2d520 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
2d530 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
2d540 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
2d550 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
2d560 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
2d570 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
2d580 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
2d590 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
2d5a0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
2d5b0 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
2d5c0 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
2d5d0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2d5e0 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
2d5f0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
2d600 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
2d610 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
2d620 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
2d630 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
2d640 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
2d650 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
2d660 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
2d670 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
2d680 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
2d690 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2d6a0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d6b0 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
2d6c0 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
2d6d0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
2d6e0 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
2d6f0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
2d700 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
2d710 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
2d720 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
2d730 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
2d740 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
2d750 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
2d760 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
2d770 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
2d780 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
2d790 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
2d7a0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
2d7b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2d7c0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2d7d0 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
2d7e0 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
2d7f0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
2d800 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2d810 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2d820 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
2d830 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
2d840 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2d850 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
2d860 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
2d870 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2d880 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2d890 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2d8a0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
2d8b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2d8c0 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
2d8d0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2d8e0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
2d8f0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
2d900 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult set.**.** ^T
2d910 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2d920 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
2d930 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
2d940 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2d950 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
2d960 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2d970 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
2d980 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d990 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
2d9a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
2d9b0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
2d9c0 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
2d9d0 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
2d9e0 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
2d9f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
2da00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2da10 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
2da20 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
2da30 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2da40 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
2da50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2da60 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2da70 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
2da80 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
2da90 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68   pointer..** ^Th
2daa0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2dab0 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2dac0 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65  returns 0 if the
2dad0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2dae0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2daf0 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20  ep](P) returned 
2db00 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2db10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2db20 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69  a_count(P).** wi
2db30 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65  ll return non-ze
2db40 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63  ro if previous c
2db50 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2db60 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2db70 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57  d.** [SQLITE_ROW
2db80 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65  ], except in the
2db90 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52   case of the [PR
2dba0 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c  AGMA incremental
2dbb0 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72  _vacuum].** wher
2dbc0 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  e it always retu
2dbd0 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65  rns zero since e
2dbe0 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74  ach step of that
2dbf0 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70   multi-step.** p
2dc00 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20  ragma returns 0 
2dc10 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e  columns of data.
2dc20 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2dc30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2dc40 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
2dc50 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2dc60 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2dc70 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2dc80 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
2dc90 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
2dca0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
2dcb0 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
2dcc0 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
2dcd0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
2dce0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
2dcf0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
2dd00 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2dd10 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
2dd20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
2dd30 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
2dd40 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2dd50 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
2dd60 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
2dd70 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
2dd80 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
2dd90 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
2dda0 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
2ddb0 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
2ddc0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
2ddd0 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
2dde0 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
2ddf0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
2de00 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
2de10 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
2de20 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
2de30 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
2de40 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
2de50 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
2de60 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
2de70 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
2de80 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
2de90 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
2dea0 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
2deb0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
2dec0 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
2ded0 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
2dee0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
2def0 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
2df00 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
2df10 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
2df20 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
2df30 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
2df40 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2df50 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
2df60 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
2df70 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
2df80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2df90 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
2dfa0 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
2dfb0 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
2dfc0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
2dfd0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2dfe0 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
2dff0 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
2e000 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
2e010 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2e020 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2e030 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
2e040 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
2e050 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
2e060 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
2e070 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
2e080 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2e090 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
2e0a0 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
2e0b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2e0c0 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
2e0d0 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
2e0e0 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
2e0f0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
2e100 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
2e110 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
2e120 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
2e130 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
2e140 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2e150 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2e160 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
2e170 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
2e180 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
2e190 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
2e1a0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
2e1b0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
2e1c0 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
2e1d0 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
2e1e0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2e1f0 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
2e200 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
2e210 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2e220 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
2e230 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
2e240 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2e250 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
2e260 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
2e270 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
2e280 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
2e290 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
2e2a0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2e2b0 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
2e2c0 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
2e2d0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
2e2e0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2e2f0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2e300 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2e310 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2e320 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
2e330 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2e340 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
2e350 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
2e360 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
2e370 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
2e380 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
2e390 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2e3a0 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
2e3b0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2e3c0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2e3d0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
2e3e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2e3f0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
2e400 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
2e410 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2e420 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
2e430 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2e440 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
2e450 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2e460 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2e470 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e480 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
2e490 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
2e4a0 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
2e4b0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2e4c0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
2e4d0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
2e4e0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2e4f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2e500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e510 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
2e520 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
2e530 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2e540 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
2e550 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
2e560 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
2e570 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
2e580 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2e590 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
2e5a0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2e5b0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
2e5c0 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
2e5d0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
2e5e0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
2e5f0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
2e600 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2e610 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2e620 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
2e630 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
2e640 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
2e650 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
2e660 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
2e670 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
2e680 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
2e690 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
2e6a0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2e6b0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2e6c0 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
2e6d0 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
2e6e0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
2e6f0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
2e700 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
2e710 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
2e720 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
2e730 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
2e740 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2e750 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2e760 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
2e770 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2e780 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
2e790 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2e7a0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2e7b0 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2e7c0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2e7d0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2e7e0 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
2e7f0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2e800 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
2e810 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2e820 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
2e830 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2e840 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2e850 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2e860 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2e870 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2e880 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2e890 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2e8a0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2e8b0 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2e8c0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
2e8d0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2e8e0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2e8f0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2e900 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2e910 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2e920 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2e930 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2e940 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2e950 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2e960 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2e970 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
2e980 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2e990 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
2e9a0 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2e9b0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2e9c0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2e9d0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2e9e0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2e9f0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
2ea00 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2ea10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2ea20 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2ea30 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2ea40 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
2ea50 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2ea60 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2ea70 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2ea80 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2ea90 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2eaa0 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
2eab0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2eac0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2ead0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2eae0 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
2eaf0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2eb00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2eb10 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2eb20 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2eb30 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2eb40 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2eb50 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
2eb60 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2eb70 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
2eb80 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2eb90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2eba0 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
2ebb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ebc0 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
2ebd0 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
2ebe0 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
2ebf0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
2ec00 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
2ec10 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
2ec20 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2ec30 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2ec40 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
2ec50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ec60 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
2ec70 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
2ec80 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
2ec90 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2eca0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
2ecb0 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
2ecc0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2ecd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2ece0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2ecf0 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
2ed00 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
2ed10 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
2ed20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
2ed30 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
2ed40 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
2ed50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2ed60 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
2ed70 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
2ed80 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2ed90 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  * ^The object re
2eda0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2edb0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2edc0 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
2edd0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ede0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
2edf0 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
2ee00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2ee10 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
2ee20 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
2ee30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2ee40 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2ee50 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2ee60 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
2ee70 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ee80 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2ee90 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2eea0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2eeb0 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
2eec0 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
2eed0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
2eee0 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
2eef0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
2ef00 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
2ef10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2ef20 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
2ef30 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2ef40 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
2ef50 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2ef60 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
2ef70 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
2ef80 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
2ef90 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
2efa0 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
2efb0 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
2efc0 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
2efd0 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
2efe0 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
2eff0 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
2f000 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
2f010 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
2f020 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
2f030 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
2f040 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
2f050 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
2f060 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
2f070 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
2f080 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
2f090 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
2f0a0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2f0b0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
2f0c0 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
2f0d0 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
2f0e0 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
2f0f0 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
2f100 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
2f110 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2f120 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2f130 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2f140 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
2f150 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
2f160 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
2f170 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
2f180 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2f190 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2f1a0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
2f1b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2f1c0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2f1d0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2f1e0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2f1f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2f200 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2f210 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
2f220 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2f230 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
2f240 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2f250 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2f260 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2f270 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2f280 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
2f290 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2f2a0 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
2f2b0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
2f2c0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
2f2d0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2f2e0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2f2f0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2f300 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
2f310 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2f320 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2f330 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2f340 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
2f350 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2f360 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2f370 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2f380 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64   BLOB.** <tr><td
2f390 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2f3a0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
2f3b0 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
2f3c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2f3d0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
2f3e0 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
2f3f0 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
2f400 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2f410 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2f420 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
2f430 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2f440 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2f450 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
2f460 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
2f470 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2f480 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2f490 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
2f4a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2f4b0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2f4c0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
2f4d0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
2f4e0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
2f4f0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
2f500 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
2f510 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
2f520 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
2f530 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
2f540 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
2f550 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
2f560 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
2f570 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
2f580 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
2f590 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
2f5a0 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
2f5b0 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
2f5c0 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
2f5d0 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
2f5e0 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
2f5f0 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
2f600 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
2f610 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
2f620 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
2f630 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
2f640 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
2f650 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
2f660 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
2f670 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
2f680 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
2f690 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2f6a0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
2f6b0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
2f6c0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
2f6d0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
2f6e0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
2f6f0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
2f700 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
2f710 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
2f720 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
2f730 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
2f740 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
2f750 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
2f760 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2f770 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
2f780 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f790 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2f7a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f7b0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2f7c0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
2f7d0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
2f7e0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
2f7f0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
2f800 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
2f810 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2f820 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
2f830 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2f840 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
2f850 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2f860 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2f870 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
2f880 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
2f890 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
2f8a0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
2f8b0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
2f8c0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2f8d0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
2f8e0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2f8f0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
2f900 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2f910 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
2f920 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2f930 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2f940 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2f950 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
2f960 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
2f970 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
2f980 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
2f990 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
2f9a0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
2f9b0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
2f9c0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
2f9d0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
2f9e0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
2f9f0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
2fa00 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
2fa10 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
2fa20 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
2fa30 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
2fa40 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
2fa50 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
2fa60 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
2fa70 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
2fa80 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
2fa90 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
2faa0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
2fab0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
2fac0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
2fad0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
2fae0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
2faf0 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
2fb00 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
2fb10 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
2fb20 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
2fb30 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
2fb40 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
2fb50 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
2fb60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2fb70 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
2fb80 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2fb90 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
2fba0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2fbb0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
2fbc0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2fbd0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2fbe0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2fbf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2fc00 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
2fc10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fc20 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
2fc30 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2fc40 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
2fc50 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
2fc60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2fc70 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
2fc80 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
2fc90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fca0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
2fcb0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
2fcc0 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
2fcd0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
2fce0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
2fcf0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2fd00 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2fd10 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2fd20 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
2fd30 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
2fd40 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
2fd50 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
2fd60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
2fd70 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2fd80 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
2fd90 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2fda0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2fdb0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
2fdc0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
2fdd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2fde0 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
2fdf0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2fe00 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
2fe10 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
2fe20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
2fe30 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
2fe40 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
2fe50 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
2fe60 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
2fe70 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
2fe80 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2fe90 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2fea0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2feb0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
2fec0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
2fed0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
2fee0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
2fef0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
2ff00 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
2ff10 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
2ff20 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
2ff30 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
2ff40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2ff50 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
2ff60 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
2ff70 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
2ff80 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
2ff90 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
2ffa0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2ffb0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
2ffc0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
2ffd0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
2ffe0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
2fff0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
30000 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
30010 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
30020 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
30030 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
30040 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
30050 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
30060 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
30070 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
30080 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
30090 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
300a0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
300b0 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
300c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
300d0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
300e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
300f0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
30100 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
30110 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30120 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
30130 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30140 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
30150 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
30160 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
30170 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
30180 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
30190 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
301a0 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
301b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
301c0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
301d0 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
301e0 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
301f0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
30200 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
30210 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
30220 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
30230 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
30240 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
30250 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30260 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
30270 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30280 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
30290 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
302a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
302b0 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
302c0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
302d0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
302e0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
302f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30300 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
30310 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
30320 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
30330 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
30340 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
30350 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
30360 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
30370 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
30380 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
30390 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
303a0 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
303b0 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
303c0 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
303d0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
303e0 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
303f0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
30400 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
30410 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
30420 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
30430 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
30440 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
30450 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
30460 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
30470 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
30480 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
30490 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
304a0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
304b0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
304c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
304d0 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
304e0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
304f0 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
30500 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
30510 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
30520 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
30530 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
30540 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
30550 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
30560 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
30570 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
30580 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
30590 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
305a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
305b0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
305c0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
305d0 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
305e0 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
305f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
30600 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
30610 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
30620 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
30630 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
30640 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
30650 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
30660 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
30670 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
30680 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
30690 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
306a0 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
306b0 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
306c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
306d0 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
306e0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
306f0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
30700 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
30710 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
30720 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
30730 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
30740 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
30750 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
30760 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
30770 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
30780 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
30790 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
307a0 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
307b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
307c0 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
307d0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
307e0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
307f0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
30800 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
30810 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
30820 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
30830 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
30840 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
30850 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
30860 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
30870 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
30880 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
30890 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
308a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
308b0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
308c0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
308d0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
308e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
308f0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
30900 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
30910 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
30920 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
30930 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
30940 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
30950 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
30960 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
30970 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
30980 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
30990 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
309a0 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
309b0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
309c0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
309d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
309e0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
309f0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
30a00 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
30a10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30a20 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
30a30 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
30a40 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
30a50 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
30a60 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
30a70 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
30a80 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
30a90 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
30aa0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
30ab0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
30ac0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
30ad0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
30ae0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
30af0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
30b00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30b10 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
30b20 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
30b30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
30b40 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
30b50 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
30b60 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
30b70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30b80 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
30b90 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
30ba0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
30bb0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
30bc0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
30bd0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
30be0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
30bf0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
30c00 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
30c10 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
30c20 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
30c30 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
30c40 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
30c50 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
30c60 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
30c70 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
30c80 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
30c90 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
30ca0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
30cb0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
30cc0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
30cd0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
30ce0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
30cf0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
30d00 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
30d10 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
30d20 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
30d30 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
30d40 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
30d50 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
30d60 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
30d70 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
30d80 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
30d90 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
30da0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
30db0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
30dc0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
30dd0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
30de0 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
30df0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
30e00 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
30e10 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
30e20 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
30e30 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
30e40 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
30e50 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
30e60 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
30e70 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
30e80 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
30e90 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
30ea0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
30eb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30ec0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
30ed0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
30ee0 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
30ef0 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
30f00 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
30f10 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
30f20 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
30f30 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
30f40 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
30f50 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
30f60 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
30f70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30f80 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
30f90 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
30fa0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
30fb0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
30fc0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30fd0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
30fe0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
30ff0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
31000 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
31010 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
31020 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
31030 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
31040 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
31050 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
31060 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
31070 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
31080 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
31090 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
310a0 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
310b0 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
310c0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
310d0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
310e0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
310f0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
31100 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
31110 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
31120 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
31130 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
31140 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
31150 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
31160 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
31170 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
31180 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
31190 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
311a0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
311b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
311c0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
311d0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
311e0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
311f0 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
31200 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
31210 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
31220 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
31230 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
31240 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
31250 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
31260 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
31270 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
31280 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
31290 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
312a0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
312b0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
312c0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
312d0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
312e0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
312f0 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
31300 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
31310 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
31320 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c  eters.  The appl
31330 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73  ication should s
31340 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  et this paramete
31350 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r to.** [SQLITE_
31360 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20  UTF16LE] if the 
31370 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
31380 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  ntation invokes 
31390 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
313a0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f  ue_text16le()] o
313b0 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b  n an input, or [
313c0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20  SQLITE_UTF16BE] 
313d0 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  if the.** implem
313e0 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
313f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
31400 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61  text16be()] on a
31410 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b  n input, or.** [
31420 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66  SQLITE_UTF16] if
31430 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
31440 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65  text16()] is use
31450 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  d, or [SQLITE_UT
31460 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  F8].** otherwise
31470 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c  .  ^The same SQL
31480 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
31490 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
314a0 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67  iple times using
314b0 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72  .** different pr
314c0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
314d0 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66  odings, with dif
314e0 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  ferent implement
314f0 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61  ations for.** ea
31500 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20  ch encoding..** 
31510 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
31520 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
31530 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
31540 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
31550 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
31560 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
31570 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
31580 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
31590 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
315a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
315b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61  rth parameter ma
315c0 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20  y optionally be 
315d0 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  ORed with [SQLIT
315e0 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d  E_DETERMINISTIC]
315f0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68  .** to signal th
31600 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  at the function 
31610 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
31620 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75  rn the same resu
31630 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20  lt given.** the 
31640 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68  same inputs with
31650 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  in a single SQL 
31660 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74  statement.  Most
31670 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
31680 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73  re.** determinis
31690 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d  tic.  The built-
316a0 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51  in [random()] SQ
316b0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e  L function is an
316c0 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a   example of a.**
316d0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69   function that i
316e0 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73  s not determinis
316f0 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65  tic.  The SQLite
31700 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69   query planner i
31710 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72  s able to.** per
31720 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20  form additional 
31730 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e  optimizations on
31740 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66   deterministic f
31750 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65  unctions, so use
31760 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
31770 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
31780 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d  ] flag is recomm
31790 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73  ended where poss
317a0 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ible..**.** ^(Th
317b0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
317c0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
317d0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
317e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
317f0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
31800 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
31810 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
31820 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
31830 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
31840 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
31850 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65  h, seventh and e
31860 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73  ighth parameters
31870 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
31880 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
31890 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
318a0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
318b0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
318c0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
318d0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
318e0 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
318f0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
31900 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
31910 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
31920 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
31930 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
31940 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  rs must be passe
31950 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
31960 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
31970 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
31980 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
31990 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
319a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
319b0 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
319c0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70  Final and NULL p
319d0 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70  ointer must be p
319e0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
319f0 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
31a00 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
31a10 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
31a20 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
31a30 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c  pointers for all
31a40 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
31a50 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
31a60 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e  .** ^(If the nin
31a70 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
31a80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31a90 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
31aa0 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
31ab0 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
31ac0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
31ad0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
31ae0 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
31af0 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
31b00 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
31b10 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
31b20 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
31b30 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
31b40 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
31b50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
31b60 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
31b70 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
31b80 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
31b90 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
31ba0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31bb0 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
31bc0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
31bd0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
31be0 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
31bf0 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
31c00 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
31c10 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
31c20 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
31c30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
31c40 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
31c50 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
31c60 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
31c70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
31c80 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31c90 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
31ca0 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
31cb0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
31cc0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
31cd0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
31ce0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
31cf0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
31d00 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
31d10 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
31d20 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
31d30 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
31d40 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
31d50 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
31d60 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
31d70 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
31d80 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
31d90 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
31da0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
31db0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
31dc0 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
31dd0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
31de0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
31df0 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
31e00 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
31e10 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
31e20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
31e30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
31e40 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
31e50 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63  e nArg.  ^A func
31e60 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
31e70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
31e80 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
31e90 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
31ea0 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
31eb0 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
31ec0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
31ed0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
31ee0 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
31ef0 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  ** ^A function w
31f00 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
31f10 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
31f20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
31f30 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
31f40 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
31f50 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
31f60 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
31f70 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
31f80 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
31f90 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
31fa0 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e  ** ^Built-in fun
31fb0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
31fc0 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
31fd0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31fe0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
31ff0 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
32000 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32010 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
32020 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
32030 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
32040 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
32050 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
32060 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
32070 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
32080 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
32090 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
320a0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
320b0 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
320c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
320d0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
320e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
320f0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
32100 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
32110 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
32120 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
32130 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
32140 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
32150 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
32160 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
32170 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
32180 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
32190 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
321a0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
321b0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
321c0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
321d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
321e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
321f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
32200 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
32210 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
32220 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
32230 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
32240 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
32250 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
32260 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
32270 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
32280 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
32290 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
322a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
322b0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
322c0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
322d0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
322e0 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
322f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32300 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  nction_v2(.  sql
32310 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
32320 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
32330 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
32340 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
32350 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
32360 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
32370 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32380 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
32390 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
323a0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
323b0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
323c0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
323d0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
323e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
323f0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
32400 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a  roy)(void*).);..
32410 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32420 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
32430 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
32440 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
32450 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
32460 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
32470 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
32480 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
32490 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
324a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
324b0 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20  8           1   
324c0 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34   /* IMP: R-37514
324d0 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e  -35566 */.#defin
324e0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
324f0 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20          2    /* 
32500 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36  IMP: R-03371-376
32510 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  37 */.#define SQ
32520 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
32530 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a      3    /* IMP:
32540 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a   R-51971-34154 *
32550 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
32560 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
32570 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
32580 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
32590 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
325a0 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
325b0 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65      /* Deprecate
325c0 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
325d0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
325e0 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
325f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32600 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
32610 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
32620 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a  ction Flags.**.*
32630 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
32640 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f  s may be ORed to
32650 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20  gether with the 
32660 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
32670 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78   | preferred tex
32680 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74  t encoding] as t
32690 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
326a0 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  nt.** to [sqlite
326b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
326c0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
326d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
326e0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
326f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32700 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64  ion_v2()]..*/.#d
32710 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
32720 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78  ERMINISTIC    0x
32730 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
32740 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
32750 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
32760 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
32770 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
32780 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
32790 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
327a0 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
327b0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
327c0 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
327d0 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
327e0 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
327f0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
32800 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
32810 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
32820 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
32830 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
32840 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
32850 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
32860 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
32870 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
32880 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
32890 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
328a0 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
328b0 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
328c0 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
328d0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
328e0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
328f0 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
32900 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32910 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
32920 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
32930 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
32940 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
32950 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
32960 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
32970 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
32980 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
32990 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
329a0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
329b0 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
329c0 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
329d0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
329e0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
329f0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
32a00 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
32a10 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
32a20 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
32a30 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
32a40 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20  _int64,int),.   
32a50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32a60 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33     void*,sqlite3
32a70 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
32a80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32a90 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
32aa0 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
32ab0 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
32ac0 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
32ad0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
32ae0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
32af0 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
32b00 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
32b10 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
32b20 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
32b30 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
32b40 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
32b50 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
32b60 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
32b70 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
32b80 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
32b90 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
32ba0 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
32bb0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
32bc0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
32bd0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
32be0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
32bf0 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
32c00 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
32c10 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
32c20 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
32c30 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
32c40 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
32c50 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
32c60 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
32c70 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
32c80 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
32c90 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
32ca0 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
32cb0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
32cc0 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
32cd0 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
32ce0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
32cf0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
32d00 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
32d10 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
32d20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
32d30 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
32d40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
32d50 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
32d60 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
32d70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
32d80 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
32d90 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
32da0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
32db0 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
32dc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
32dd0 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
32de0 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
32df0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
32e00 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
32e10 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
32e20 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
32e30 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
32e40 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
32e50 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72  ept that these r
32e60 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
32e70 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
32e80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
32e90 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
32ea0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
32eb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
32ec0 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
32ed0 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
32ee0 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
32ef0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32f00 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
32f10 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
32f20 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
32f30 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
32f40 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
32f50 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
32f60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
32f70 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
32f80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
32f90 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
32fa0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
32fb0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
32fc0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
32fd0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
32fe0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
32ff0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
33000 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
33010 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
33020 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
33030 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
33040 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
33050 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
33060 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
33070 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
33080 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
33090 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
330a0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
330b0 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
330c0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
330d0 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
330e0 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
330f0 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
33100 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
33110 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
33120 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
33130 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
33140 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
33150 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
33160 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
33170 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
33180 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
33190 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
331a0 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
331b0 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
331c0 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
331d0 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
331e0 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
331f0 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
33200 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
33210 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
33220 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
33230 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
33240 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
33250 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
33260 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
33270 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
33280 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
33290 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
332a0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
332b0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
332c0 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
332d0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
332e0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
332f0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
33300 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
33310 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
33320 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
33330 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
33340 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
33350 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
33360 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
33370 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
33380 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
33390 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
333a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
333b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
333c0 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
333d0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
333e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
333f0 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
33400 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  e*);.double sqli
33410 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
33420 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33430 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
33440 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
33450 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33  value*);.sqlite3
33460 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
33470 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
33480 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
33490 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
334a0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
334b0 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
334c0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
334d0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
334e0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
334f0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
33500 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
33510 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
33520 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
33530 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
33540 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
33550 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
33560 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
33570 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
33580 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
33590 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
335a0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
335b0 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
335c0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
335d0 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
335e0 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  n Context.**.** 
335f0 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
33600 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
33610 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
33620 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
33630 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
33640 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
33650 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
33660 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
33670 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
33680 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
33690 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
336a0 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
336b0 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
336c0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
336d0 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
336e0 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
336f0 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
33700 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
33710 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
33720 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
33730 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
33740 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
33750 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
33760 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
33770 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
33780 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
33790 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
337a0 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
337b0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
337c0 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
337d0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
337e0 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
337f0 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
33800 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
33810 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
33820 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
33830 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
33840 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
33850 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
33860 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
33870 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
33880 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
33890 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
338a0 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
338b0 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
338c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
338d0 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
338e0 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
338f0 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
33900 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
33910 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
33920 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33930 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
33940 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
33950 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
33960 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
33970 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33980 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33990 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
339a0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
339b0 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68  L pointer .** wh
339c0 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20  en first called 
339d0 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  if N is less tha
339e0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
339f0 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  ro or if a memor
33a00 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72  y.** allocate er
33a10 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
33a20 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
33a30 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
33a40 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
33a50 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
33a60 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
33a70 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
33a80 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
33a90 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
33aa0 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
33ab0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
33ac0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
33ad0 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
33ae0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
33af0 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
33b00 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
33b10 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
33b20 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
33b30 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
33b40 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68  ocation.)^  With
33b50 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  in the xFinal ca
33b60 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75  llback, it is cu
33b70 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a  stomary to set.*
33b80 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74  * N=0 in calls t
33b90 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
33ba0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
33bb0 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20   so that no .** 
33bc0 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79  pointless memory
33bd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63   allocations occ
33be0 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ur..**.** ^SQLit
33bf0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
33c00 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
33c10 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
33c20 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
33c30 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
33c40 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
33c50 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
33c60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
33c70 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
33c80 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
33c90 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
33ca0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
33cb0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
33cc0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
33cd0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
33ce0 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
33cf0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
33d00 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
33d10 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
33d20 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
33d30 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
33d40 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
33d50 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
33d60 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
33d70 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
33d80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
33d90 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
33da0 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
33db0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
33dc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
33dd0 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
33de0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
33df0 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
33e00 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
33e10 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
33e20 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
33e30 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
33e40 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
33e50 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
33e60 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
33e70 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
33e80 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
33e90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33ea0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
33eb0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33ec0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
33ed0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
33ee0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
33ef0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
33f00 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
33f10 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
33f20 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
33f30 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
33f40 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
33f50 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
33f60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33f70 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
33f80 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
33f90 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
33fa0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
33fb0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
33fc0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
33fd0 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
33fe0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
33ff0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
34000 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
34010 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
34020 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
34030 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
34040 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
34050 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
34060 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
34070 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
34080 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
34090 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
340a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
340b0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
340c0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
340d0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
340e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
340f0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
34100 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
34110 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
34120 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
34130 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
34140 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
34150 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
34160 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  a.**.** These fu
34170 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
34180 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72  sed by (non-aggr
34190 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74  egate) SQL funct
341a0 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
341b0 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
341c0 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
341d0 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
341e0 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
341f0 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
34200 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
34210 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
34220 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
34230 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
34240 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
34250 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
34260 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
34270 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
34280 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a  .  An example.**
34290 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d   of where this m
342a0 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69  ight be useful i
342b0 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65  s in a regular-e
342c0 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
342d0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ng.** function. 
342e0 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
342f0 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
34300 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
34310 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a  an be stored as.
34320 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  ** metadata asso
34330 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
34340 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20  pattern string. 
34350 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e   .** Then as lon
34360 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e  g as the pattern
34370 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20   string remains 
34380 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65  the same,.** the
34390 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
343a0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
343b0 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
343c0 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
343d0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
343e0 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  e function..**.*
343f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
34400 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
34410 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
34420 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
34430 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
34440 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
34450 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
34460 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
34470 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
34480 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
34490 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
344a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
344b0 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f   ^If there is no
344c0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
344d0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
344e0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
344f0 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33  nt, this sqlite3
34500 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
34510 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
34520 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
34530 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
34540 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34550 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65  ta(C,N,P,X) inte
34560 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73  rface saves P as
34570 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
34580 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
34590 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
345a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
345b0 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71  nction.  ^Subseq
345c0 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
345d0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
345e0 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e  data(C,N) return
345f0 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74   P from the most
34600 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74   recent.** sqlit
34610 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
34620 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20  ,N,P,X) call if 
34630 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
34640 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a  still valid or.*
34650 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65  * NULL if the me
34660 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
34670 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41  discarded..** ^A
34680 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74  fter each call t
34690 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
346a0 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77  xdata(C,N,P,X) w
346b0 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55  here X is not NU
346c0 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  LL,.** SQLite wi
346d0 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
346e0 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
346f0 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74  n X with paramet
34700 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20  er P exactly.** 
34710 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d  once, when the m
34720 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61  etadata is disca
34730 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  rded..** SQLite 
34740 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61  is free to disca
34750 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  rd the metadata 
34760 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63  at any time, inc
34770 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20  luding: <ul>.** 
34780 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f  <li> when the co
34790 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
347a0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
347b0 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c  hanges, or.** <l
347c0 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  i> when [sqlite3
347d0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
347e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
347f0 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20  ] is called for 
34800 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20  the.**      SQL 
34810 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a  statement, or.**
34820 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74   <li> when sqlit
34830 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
34840 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69   is invoked agai
34850 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61  n on the same pa
34860 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c  rameter, or.** <
34870 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f  li> during the o
34880 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f  riginal sqlite3_
34890 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61  set_auxdata() ca
348a0 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79  ll when a memory
348b0 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61   .**      alloca
348c0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
348d0 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  s. </ul>)^.**.**
348e0 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62   Note the last b
348f0 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75  ullet in particu
34900 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75  lar.  The destru
34910 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71  ctor X in .** sq
34920 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
34930 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74  a(C,N,P,X) might
34940 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64   be called immed
34950 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74  iately, before t
34960 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  he.** sqlite3_se
34970 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
34980 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72  rface even retur
34990 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74  ns.  Hence sqlit
349a0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
349b0 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61  .** should be ca
349c0 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e  lled near the en
349d0 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  d of the functio
349e0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
349f0 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63   and the.** func
34a00 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
34a10 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d  ion should not m
34a20 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50  ake any use of P
34a30 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65   after.** sqlite
34a40 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
34a50 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e  has been called.
34a60 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63  .**.** ^(In prac
34a70 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
34a80 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
34a90 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
34aa0 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ls for.** functi
34ab0 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  on parameters th
34ac0 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74  at are compile-t
34ad0 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69  ime constants, i
34ae0 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c  ncluding literal
34af0 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b  .** values and [
34b00 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20  parameters] and 
34b10 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70  expressions comp
34b20 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  osed from the sa
34b30 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  me.)^.**.** Thes
34b40 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
34b50 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
34b60 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
34b70 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
34b80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
34b90 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
34ba0 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
34bb0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
34bc0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76  text*, int N);.v
34bd0 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
34be0 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
34bf0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
34c00 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
34c10 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
34c20 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
34c30 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
34c40 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
34c50 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
34c60 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
34c70 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
34c80 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
34c90 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
34ca0 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
34cb0 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
34cc0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
34cd0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
34ce0 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72  .  ^If the destr
34cf0 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
34d00 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
34d10 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
34d20 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
34d30 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
34d40 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
34d50 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
34d60 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
34d70 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
34d80 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  ^The.** SQLITE_T
34d90 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
34da0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
34db0 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
34dc0 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
34dd0 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
34de0 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
34df0 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
34e00 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
34e10 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
34e20 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
34e30 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
34e40 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
34e50 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
34e60 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
34e70 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
34e80 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64  pilers..*/.typed
34e90 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
34ea0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
34eb0 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
34ec0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
34ed0 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
34ee0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
34ef0 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
34f00 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
34f10 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
34f20 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
34f30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
34f40 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
34f50 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
34f60 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
34f70 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
34f80 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
34f90 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
34fa0 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
34fb0 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
34fc0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
34fd0 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
34fe0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34ff0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
35000 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35010 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
35020 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
35030 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
35040 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
35050 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
35060 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
35070 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
35080 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
35090 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
350a0 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
350b0 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
350c0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
350d0 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
350e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
350f0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
35100 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
35110 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
35120 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35130 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
35140 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
35150 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
35160 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35170 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
35180 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
35190 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
351a0 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
351b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
351c0 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
351d0 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
351e0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
351f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
35200 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35210 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
35220 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
35230 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
35240 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
35250 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35260 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
35270 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
35280 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
35290 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
352a0 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
352b0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
352c0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
352d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
352e0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
352f0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
35300 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
35310 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
35320 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35330 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
35340 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
35350 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
35360 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35370 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
35380 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35390 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
353a0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
353b0 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
353c0 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
353d0 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
353e0 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
353f0 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
35400 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
35410 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
35420 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
35430 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
35440 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
35450 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
35460 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
35470 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
35480 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
35490 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
354a0 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
354b0 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
354c0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
354d0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
354e0 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
354f0 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
35500 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
35510 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35520 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
35530 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
35540 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
35550 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
35560 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
35570 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
35580 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
35590 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
355a0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
355b0 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
355c0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
355d0 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
355e0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
355f0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
35600 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
35610 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
35620 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35630 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
35640 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
35650 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
35660 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
35670 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
35680 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
35690 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
356a0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
356b0 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
356c0 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
356d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
356e0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
356f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
35700 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
35710 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
35720 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
35730 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
35740 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
35750 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
35760 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
35770 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
35780 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
35790 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
357a0 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
357b0 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
357c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
357d0 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
357e0 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
357f0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
35800 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
35810 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
35820 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
35830 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
35840 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
35850 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
35860 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
35870 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
35880 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35890 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
358a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
358b0 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
358c0 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
358d0 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
358e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
358f0 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
35900 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
35910 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
35920 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
35930 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
35940 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
35950 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f  B is too long to
35960 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
35970 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
35980 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
35990 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
359a0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
359b0 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
359c0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
359d0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
359e0 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
359f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35a00 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
35a10 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
35a20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
35a30 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
35a40 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35a50 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
35a60 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
35a70 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
35a80 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
35a90 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
35aa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
35ab0 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  nt64() interface
35ac0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
35ad0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
35ae0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35af0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
35b00 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73   be the 64-bit s
35b10 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
35b20 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
35b30 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
35b40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
35b50 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
35b60 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
35b70 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
35b80 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
35b90 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35ba0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
35bb0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
35bc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35bd0 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
35be0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
35bf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
35c00 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
35c10 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
35c20 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
35c30 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
35c40 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
35c50 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
35c60 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35c70 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
35c80 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
35c90 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
35ca0 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
35cb0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
35cc0 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
35cd0 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
35ce0 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
35cf0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
35d00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35d10 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34 28 29  _result_text64()
35d20 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
35d30 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
35d40 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63   of an.** applic
35d50 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35d60 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 74  nction to be a t
35d70 65 78 74 20 73 74 72 69 6e 67 20 69 6e 20 61 6e  ext string in an
35d80 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73 70 65   encoding.** spe
35d90 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
35da0 66 74 68 20 28 61 6e 64 20 6c 61 73 74 29 20 70  fth (and last) p
35db0 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20  arameter, which 
35dc0 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a 20 6f  must be one.** o
35dd0 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
35de0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
35df0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
35e00 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
35e10 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 4c 69  F16LE]..** ^SQLi
35e20 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
35e30 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
35e40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
35e50 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
35e60 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
35e70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35e80 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
35e90 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
35ea0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
35eb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35ec0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
35ed0 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
35ee0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
35ef0 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
35f00 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
35f10 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
35f20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
35f30 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
35f40 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
35f50 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
35f60 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
35f70 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
35f80 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
35f90 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
35fa0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
35fb0 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
35fc0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
35fd0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
35fe0 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
35ff0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
36000 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
36010 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68  n result.  If th
36020 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
36030 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
36040 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74   then it.** must
36050 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
36060 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72  set into the str
36070 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55  ing where the NU
36080 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
36090 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20  ld.** appear if 
360a0 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
360b0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e   NUL terminated.
360c0 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
360d0 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a  racters occur.**
360e0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61   in the string a
360f0 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20  t a byte offset 
36100 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61  that is less tha
36110 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
36120 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65  he 3rd.** parame
36130 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ter, then the re
36140 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77  sulting string w
36150 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  ill contain embe
36160 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68  dded NULs and th
36170 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65  e.** result of e
36180 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61  xpressions opera
36190 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20  ting on strings 
361a0 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
361b0 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
361c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
361d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
361e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
361f0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
36200 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
36210 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
36220 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
36230 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
36240 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
36250 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
36260 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
36270 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
36280 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
36290 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
362a0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
362b0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
362c0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
362d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
362e0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20  * interfaces or 
362f0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  to.** sqlite3_re
36300 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
36310 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
36320 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
36330 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
36340 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
36350 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
36360 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
36370 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
36380 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
36390 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
363a0 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20  e parameter nor 
363b0 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
363c0 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74  r on the content
363d0 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20  .** when it has 
363e0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
363f0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
36400 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
36410 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
36420 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
36430 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
36440 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
36450 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
36460 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
36470 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
36480 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
36490 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
364a0 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
364b0 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
364c0 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
364d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
364e0 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
364f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36500 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
36510 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
36520 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
36530 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
36540 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
36550 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
36560 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
36570 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
36580 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
36590 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
365a0 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a  arameter.  ^The.
365b0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
365c0 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
365d0 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
365e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
365f0 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
36600 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
36610 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
36620 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
36630 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
36640 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
36650 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
36660 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
36670 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
36680 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74  arm..** ^A [prot
36690 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
366a0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
366b0 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
366c0 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
366d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
366e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
366f0 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
36700 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
36710 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
36720 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
36730 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
36740 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
36750 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
36760 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
36770 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
36780 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
36790 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
367a0 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
367b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
367c0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
367d0 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
367e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
367f0 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
36800 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
36810 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
36820 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
36830 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36840 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
36850 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
36860 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
36870 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 36 34 28 73  _result_blob64(s
36880 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36890 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 0a 20 20 20  const void*,.   
368a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
368b0 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
368c0 75 69 6e 74 36 34 2c 76 6f 69 64 28 2a 29 28 76  uint64,void(*)(v
368d0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
368e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
368f0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
36900 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
36910 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36920 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
36930 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
36940 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
36950 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36960 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
36970 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
36980 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
36990 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
369a0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
369b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
369c0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
369d0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
369e0 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
369f0 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
36a00 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
36a10 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
36a20 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
36a30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36a40 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
36a50 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
36a60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36a70 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
36a80 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
36a90 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
36aa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
36ab0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36ac0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
36ad0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
36ae0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
36af0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
36b00 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
36b10 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36b20 65 73 75 6c 74 5f 74 65 78 74 36 34 28 73 71 6c  esult_text64(sql
36b30 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
36b40 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
36b50 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
36b60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36b70 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
36b80 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63  id*), unsigned c
36b90 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 76  har encoding);.v
36ba0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36bb0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
36bc0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
36bd0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
36be0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
36bf0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36c00 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
36c10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
36c20 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
36c30 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
36c40 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36c50 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
36c60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
36c70 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
36c80 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
36c90 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36ca0 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
36cb0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
36cc0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
36cd0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36ce0 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
36cf0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
36d00 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
36d10 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
36d20 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
36d30 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  nces.**.** ^Thes
36d40 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
36d50 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
36d60 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
36d70 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
36d80 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
36d90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
36da0 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
36db0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
36dc0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
36dd0 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
36de0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
36df0 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
36e00 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36e10 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
36e20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36e30 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
36e40 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
36e50 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
36e60 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
36e70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
36e80 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
36e90 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
36ea0 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
36eb0 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
36ec0 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
36ed0 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
36ee0 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
36ef0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
36f00 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
36f10 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
36f20 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
36f30 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
36f40 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
36f50 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
36f60 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
36f70 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
36f80 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
36f90 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
36fa0 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
36fb0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
36fc0 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
36fd0 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
36fe0 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
36ff0 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
37000 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
37010 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
37020 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37030 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
37040 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
37050 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
37060 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
37070 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
37080 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
37090 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
370a0 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
370b0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
370c0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
370d0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
370e0 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
370f0 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
37100 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
37110 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
37120 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
37130 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
37140 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20  nt, pArg, is an 
37150 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
37160 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
37170 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75   passed.** throu
37180 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
37190 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
371a0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
371b0 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
371c0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
371d0 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63  gument, xCallbac
371e0 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  k, is a pointer 
371f0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
37200 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d   function..** ^M
37210 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e  ultiple collatin
37220 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  g functions can 
37230 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73  be registered us
37240 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
37250 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69  e but.** with di
37260 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
37270 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
37280 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
37290 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e  whichever.** fun
372a0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74  ction requires t
372b0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
372c0 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72  of data transfor
372d0 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  mation..** ^If t
372e0 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67  he xCallback arg
372f0 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68  ument is NULL th
37300 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  en the collating
37310 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
37320 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20  deleted.  ^When 
37330 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  all collating fu
37340 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74  nctions having t
37350 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  he same name are
37360 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61   deleted,.** tha
37370 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e  t collation is n
37380 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e  o longer usable.
37390 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c  .**.** ^The coll
373a0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
373b0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
373c0 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f  ed with a copy o
373d0 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61  f the pArg .** a
373e0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
373f0 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68  pointer and with
37400 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20   two strings in 
37410 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
37420 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
37430 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
37440 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69  nt.  The collati
37450 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
37460 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e   return an.** in
37470 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65  teger that is ne
37480 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72  gative, zero, or
37490 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20   positive.** if 
374a0 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
374b0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65   is less than, e
374c0 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
374d0 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
374e0 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ond,.** respecti
374f0 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69  vely.  A collati
37500 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
37510 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
37520 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a  he same answer.*
37530 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65  * given the same
37540 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f   inputs.  If two
37550 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69   or more collati
37560 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
37570 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74   registered.** t
37580 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61  o the same colla
37590 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67  tion name (using
375a0 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
375b0 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e  Rep values) then
375c0 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76   all.** must giv
375d0 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20  e an equivalent 
375e0 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f  answer when invo
375f0 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c  ked with equival
37600 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  ent strings..** 
37610 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
37620 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79  nction must obey
37630 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70   the following p
37640 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c  roperties for al
37650 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20  l.** strings A, 
37660 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20  B, and C:.**.** 
37670 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  <ol>.** <li> If 
37680 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a  A==B then B==A..
37690 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
376a0 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d  and B==C then A=
376b0 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =C..** <li> If A
376c0 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b  &lt;B THEN B&gt;
376d0 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  A..** <li> If A&
376e0 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20  lt;B and B&lt;C 
376f0 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20  then A&lt;C..** 
37700 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  </ol>.**.** If a
37710 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37720 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66  ion fails any of
37730 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74   the above const
37740 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a  raints and that.
37750 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ** collating fun
37760 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74  ction is  regist
37770 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74  ered and used, t
37780 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
37790 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73   of SQLite.** is
377a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
377b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
377c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
377d0 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
377e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
377f0 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69  ollation().** wi
37800 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20  th the addition 
37810 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f  that the xDestro
37820 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  y callback is in
37830 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68  voked on pArg wh
37840 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  en.** the collat
37850 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
37860 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c  deleted..** ^Col
37870 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
37880 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65   are deleted whe
37890 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
378a0 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a  idden by later.*
378b0 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63  * calls to the c
378c0 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
378d0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
378e0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  hen the.** [data
378f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37900 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
37910 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
37920 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  )]..**.** ^The x
37930 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
37940 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63   is <u>not</u> c
37950 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a  alled if the .**
37960 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37970 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66  collation_v2() f
37980 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  unction fails.  
37990 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
379a0 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  t invoke.** sqli
379b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
379c0 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61  tion_v2() with a
379d0 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72   non-NULL xDestr
379e0 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  oy argument shou
379f0 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65  ld .** check the
37a00 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64   return code and
37a10 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
37a20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
37a30 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d   pointer.** them
37a40 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68  selves rather th
37a50 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c  an expecting SQL
37a60 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68  ite to deal with
37a70 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a   it for them..**
37a80 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65   This is differe
37a90 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74  nt from every ot
37aa0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
37ab0 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e  face.  The incon
37ac0 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20  sistency .** is 
37ad0 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20  unfortunate but 
37ae0 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
37af0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
37b00 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a  ng backwards .**
37b10 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
37b20 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
37b30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
37b40 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
37b50 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  d [sqlite3_colla
37b60 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d  tion_needed16()]
37b70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
37b80 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37b90 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
37ba0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
37bb0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
37bc0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
37bd0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
37be0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
37bf0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
37c00 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
37c10 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
37c20 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
37c30 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
37c40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
37c50 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
37c60 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
37c70 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
37c80 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
37c90 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
37ca0 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
37cb0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
37cc0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
37cd0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37ce0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
37cf0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
37d00 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
37d10 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
37d20 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
37d30 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
37d40 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
37d50 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
37d60 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
37d70 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
37d80 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a  eeded Callbacks.
37d90 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20  **.** ^To avoid 
37da0 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
37db0 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
37dc0 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
37dd0 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
37de0 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
37df0 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
37e00 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
37e10 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
37e20 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
37e30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
37e40 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
37e50 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
37e60 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
37e70 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
37e80 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
37e90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
37ea0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
37eb0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
37ec0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
37ed0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
37ee0 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
37ef0 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
37f00 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
37f10 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
37f20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
37f30 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  . ^If sqlite3_co
37f40 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
37f50 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
37f60 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
37f70 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
37f80 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
37f90 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
37fa0 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
37fb0 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
37fc0 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20  es the existing 
37fd0 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64  collation-needed
37fe0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
37ff0 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c   ^(When the call
38000 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
38010 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
38020 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
38030 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
38040 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
38050 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
38060 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
38070 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
38080 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
38090 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
380a0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
380b0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
380c0 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
380d0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
380e0 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
380f0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
38100 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
38110 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
38120 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
38130 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
38140 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
38150 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
38160 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
38170 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
38180 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
38190 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
381a0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
381b0 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  quence.)^.**.** 
381c0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
381d0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
381e0 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
381f0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
38200 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
38210 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
38220 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
38230 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
38240 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
38250 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
38260 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  on_v2()]..*/.int
38270 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
38280 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
38290 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
382a0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
382b0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
382c0 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
382d0 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
382e0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
382f0 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
38300 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
38310 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
38320 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
38330 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
38340 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  .);..#ifdef SQLI
38350 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a  TE_HAS_CODEC./*.
38360 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b  ** Specify the k
38370 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70  ey for an encryp
38380 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54  ted database.  T
38390 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  his routine shou
383a0 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20  ld be.** called 
383b0 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69  right after sqli
383c0 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a  te3_open()..**.*
383d0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
383e0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
383f0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
38400 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
38410 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
38420 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
38430 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69  ite3_key(.  sqli
38440 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
38450 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
38460 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
38470 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
38480 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
38490 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
384a0 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  key */.);.int sq
384b0 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20  lite3_key_v2(.  
384c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
384d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
384e0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
384f0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
38500 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
38510 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  e,           /* 
38520 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  Name of the data
38530 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
38540 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
38550 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
38560 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
38570 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
38580 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
38590 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
385a0 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
385b0 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
385c0 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
385d0 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
385e0 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
385f0 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
38600 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
38610 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
38620 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
38630 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
38640 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
38650 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
38660 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
38670 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
38680 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
38690 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
386a0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
386b0 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
386c0 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
386d0 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
386e0 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
386f0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73   key */.);.int s
38700 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76 32 28  qlite3_rekey_v2(
38710 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
38720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38730 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
38740 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
38750 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
38760 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20  Name,           
38770 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64  /* Name of the d
38780 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
38790 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
387a0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
387b0 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
387c0 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
387d0 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
387e0 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74  ey for a SEE dat
387f0 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
38800 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
38810 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f  ne of the SEE ro
38820 75 74 6