Documentation Source Text

Hex Artifact Content
Login

Artifact 5deca9a540a3916255c3be42711e9454b307c4f9:


0000: 3c 74 69 74 6c 65 3e 54 68 65 20 4f 53 20 42 61  <title>The OS Ba
0010: 63 6b 65 6e 64 20 28 56 46 53 29 20 54 6f 20 53  ckend (VFS) To S
0020: 51 4c 69 74 65 3c 2f 74 69 74 6c 65 3e 0a 3c 74  QLite</title>.<t
0030: 63 6c 3e 68 64 5f 6b 65 79 77 6f 72 64 73 20 56  cl>hd_keywords V
0040: 46 53 20 56 46 53 65 73 20 7b 4f 53 20 62 61 63  FS VFSes {OS bac
0050: 6b 65 6e 64 7d 3c 2f 74 63 6c 3e 0a 0a 3c 68 31  kend}</tcl>..<h1
0060: 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e   align="center">
0070: 0a 54 68 65 20 53 51 4c 69 74 65 20 4f 53 20 49  .The SQLite OS I
0080: 6e 74 65 72 66 61 63 65 20 6f 72 20 22 56 46 53  nterface or "VFS
0090: 22 0a 3c 2f 68 31 3e 0a 0a 3c 70 3e 0a 54 68 69  ".</h1>..<p>.Thi
00a0: 73 20 61 72 74 69 63 6c 65 20 64 65 73 63 72 69  s article descri
00b0: 62 65 73 20 74 68 65 20 53 51 4c 69 74 65 20 4f  bes the SQLite O
00c0: 53 20 70 6f 72 74 61 62 69 6c 69 74 79 20 6c 61  S portability la
00d0: 79 65 72 20 6f 72 20 22 56 46 53 22 20 2d 20 74  yer or "VFS" - t
00e0: 68 65 0a 6d 6f 64 75 6c 65 20 61 74 20 74 68 65  he.module at the
00f0: 20 62 6f 74 74 6f 6d 20 6f 66 20 74 68 65 20 53   bottom of the S
0100: 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61  QLite implementa
0110: 74 69 6f 6e 20 73 74 61 63 6b 0a 74 68 61 74 20  tion stack.that 
0120: 70 72 6f 76 69 64 65 73 20 70 6f 72 74 61 62 69  provides portabi
0130: 6c 69 74 79 20 61 63 72 6f 73 73 20 6f 70 65 72  lity across oper
0140: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 2e 0a 3c  ating systems..<
0150: 2f 70 3e 0a 0a 3c 69 6d 67 20 73 72 63 3d 22 69  /p>..<img src="i
0160: 6d 61 67 65 73 2f 76 66 73 31 2e 67 69 66 22 20  mages/vfs1.gif" 
0170: 61 6c 69 67 6e 3d 22 72 69 67 68 74 22 20 68 73  align="right" hs
0180: 70 61 63 65 3d 22 31 30 22 3e 0a 3c 68 32 3e 31  pace="10">.<h2>1
0190: 2e 30 20 54 68 65 20 56 46 53 20 49 6e 20 52 65  .0 The VFS In Re
01a0: 6c 61 74 69 6f 6e 20 54 6f 20 54 68 65 20 52 65  lation To The Re
01b0: 73 74 20 4f 66 20 53 51 4c 69 74 65 3c 2f 68 32  st Of SQLite</h2
01c0: 3e 0a 0a 3c 70 3e 0a 54 68 65 20 69 6e 74 65 72  >..<p>.The inter
01d0: 6e 61 6c 20 6f 72 67 61 6e 69 7a 61 74 69 6f 6e  nal organization
01e0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
01f0: 69 62 72 61 72 79 20 63 61 6e 20 62 65 20 76 69  ibrary can be vi
0200: 65 77 65 64 20 61 73 20 74 68 65 0a 73 74 61 63  ewed as the.stac
0210: 6b 20 6f 66 20 6d 6f 64 75 6c 65 73 20 73 68 6f  k of modules sho
0220: 77 6e 20 74 6f 20 74 68 65 20 72 69 67 68 74 2e  wn to the right.
0230: 0a 54 68 65 20 54 6f 6b 65 6e 69 7a 65 72 2c 20  .The Tokenizer, 
0240: 50 61 72 73 65 72 2c 20 61 6e 64 20 43 6f 64 65  Parser, and Code
0250: 20 47 65 6e 65 72 61 74 6f 72 20 63 6f 6d 70 6f   Generator compo
0260: 6e 65 6e 74 73 20 61 72 65 20 75 73 65 64 20 74  nents are used t
0270: 6f 0a 70 72 6f 63 65 73 73 20 53 51 4c 20 73 74  o.process SQL st
0280: 61 74 65 6d 65 6e 74 73 20 61 6e 64 20 63 6f 6e  atements and con
0290: 76 65 72 74 20 74 68 65 6d 20 69 6e 74 6f 20 65  vert them into e
02a0: 78 65 63 75 74 61 62 6c 65 20 70 72 6f 67 72 61  xecutable progra
02b0: 6d 73 20 0a 69 6e 20 61 20 76 69 72 74 75 61 6c  ms .in a virtual
02c0: 20 6d 61 63 68 69 6e 65 20 6c 61 6e 67 75 61 67   machine languag
02d0: 65 20 6f 72 20 62 79 74 65 20 63 6f 64 65 2e 0a  e or byte code..
02e0: 52 6f 75 67 68 6c 79 20 73 70 65 61 6b 69 6e 67  Roughly speaking
02f0: 2c 20 74 68 65 73 65 20 74 6f 70 20 74 68 72 65  , these top thre
0300: 65 20 6c 61 79 65 72 73 20 69 6d 70 6c 65 6d 65  e layers impleme
0310: 6e 74 0a 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nt.[sqlite3_prep
0320: 61 72 65 5f 76 32 28 29 5d 2e 20 20 54 68 65 20  are_v2()].  The 
0330: 62 79 74 65 20 63 6f 64 65 20 67 65 6e 65 72 61  byte code genera
0340: 74 65 64 20 62 79 20 74 68 65 20 74 6f 70 20 74  ted by the top t
0350: 68 72 65 65 0a 6c 61 79 65 72 73 20 69 73 20 61  hree.layers is a
0360: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
0370: 6d 65 6e 74 5d 2e 0a 54 68 65 20 56 69 72 74 75  ment]..The Virtu
0380: 61 6c 20 4d 61 63 68 69 6e 65 20 6d 6f 64 75 6c  al Machine modul
0390: 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
03a0: 20 66 6f 72 20 72 75 6e 6e 69 6e 67 20 74 68 65   for running the
03b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 0a   SQL statement .
03c0: 62 79 74 65 20 63 6f 64 65 2e 20 54 68 65 20 42  byte code. The B
03d0: 2d 54 72 65 65 20 6d 6f 64 75 6c 65 20 6f 72 67  -Tree module org
03e0: 61 6e 69 7a 65 73 20 61 20 64 61 74 61 62 61 73  anizes a databas
03f0: 65 20 66 69 6c 65 20 69 6e 74 6f 20 6d 75 6c 74  e file into mult
0400: 69 70 6c 65 20 0a 6b 65 79 2f 76 61 6c 75 65 20  iple .key/value 
0410: 73 74 6f 72 65 73 20 77 69 74 68 20 6f 72 64 65  stores with orde
0420: 72 65 64 20 6b 65 79 73 20 61 6e 64 20 6c 6f 67  red keys and log
0430: 61 72 69 74 68 6d 69 63 20 70 65 72 66 6f 72 6d  arithmic perform
0440: 61 6e 63 65 2e 20 0a 54 68 65 20 50 61 67 65 72  ance. .The Pager
0450: 20 6d 6f 64 75 6c 65 20 69 73 20 72 65 73 70 6f   module is respo
0460: 6e 73 69 62 6c 65 20 66 6f 72 20 6c 6f 61 64 69  nsible for loadi
0470: 6e 67 20 70 61 67 65 73 20 6f 66 20 74 68 65 20  ng pages of the 
0480: 64 61 74 61 62 61 73 65 0a 66 69 6c 65 20 69 6e  database.file in
0490: 74 6f 20 6d 65 6d 6f 72 79 2c 20 66 6f 72 20 69  to memory, for i
04a0: 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 61 6e 64 20  mplementing and 
04b0: 63 6f 6e 74 72 6f 6c 6c 69 6e 67 20 74 72 61 6e  controlling tran
04c0: 73 61 63 74 69 6f 6e 73 2c 20 61 6e 64 20 0a 66  sactions, and .f
04d0: 6f 72 20 63 72 65 61 74 69 6e 67 20 61 6e 64 20  or creating and 
04e0: 6d 61 69 6e 74 61 69 6e 69 6e 67 20 74 68 65 20  maintaining the 
04f0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 73 20 74 68  journal files th
0500: 61 74 20 70 72 65 76 65 6e 74 20 64 61 74 61 62  at prevent datab
0510: 61 73 65 20 0a 63 6f 72 72 75 70 74 69 6f 6e 20  ase .corruption 
0520: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
0530: 68 20 6f 72 20 70 6f 77 65 72 20 66 61 69 6c 75  h or power failu
0540: 72 65 2e 20 0a 54 68 65 20 4f 53 20 49 6e 74 65  re. .The OS Inte
0550: 72 66 61 63 65 20 69 73 20 61 20 74 68 69 6e 20  rface is a thin 
0560: 61 62 73 74 72 61 63 74 69 6f 6e 20 74 68 61 74  abstraction that
0570: 20 70 72 6f 76 69 64 65 73 20 61 20 63 6f 6d 6d   provides a comm
0580: 6f 6e 20 73 65 74 20 6f 66 20 0a 72 6f 75 74 69  on set of .routi
0590: 6e 65 73 20 66 6f 72 20 61 64 61 70 74 69 6e 67  nes for adapting
05a0: 20 53 51 4c 69 74 65 20 74 6f 20 72 75 6e 20 6f   SQLite to run o
05b0: 6e 20 64 69 66 66 65 72 65 6e 74 20 6f 70 65 72  n different oper
05c0: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 2e 0a 52  ating systems..R
05d0: 6f 75 67 68 6c 79 20 73 70 65 61 6b 69 6e 67 2c  oughly speaking,
05e0: 20 74 68 65 20 62 6f 74 74 6f 6d 20 66 6f 75 72   the bottom four
05f0: 20 6c 61 79 65 72 73 20 69 6d 70 6c 65 6d 65 6e   layers implemen
0600: 74 0a 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  t.[sqlite3_step(
0610: 29 5d 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68  )]..</p>..<p>.Th
0620: 69 73 20 61 72 74 69 63 6c 65 20 69 73 20 61 62  is article is ab
0630: 6f 75 74 20 74 68 65 20 62 6f 74 74 6f 6d 20 6c  out the bottom l
0640: 61 79 65 72 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 54  ayer..</p>..<p>T
0650: 68 65 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  he OS Interface 
0660: 2d 20 61 6c 73 6f 20 63 61 6c 6c 65 64 20 74 68  - also called th
0670: 65 20 22 56 46 53 22 20 2d 20 69 73 20 77 68 61  e "VFS" - is wha
0680: 74 20 6d 61 6b 65 73 20 53 51 4c 69 74 65 20 0a  t makes SQLite .
0690: 70 6f 72 74 61 62 6c 65 20 61 63 72 6f 73 73 20  portable across 
06a0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
06b0: 73 2e 20 20 57 68 65 6e 65 76 65 72 20 61 6e 79  s.  Whenever any
06c0: 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 6d 6f   of the other mo
06d0: 64 75 6c 65 73 0a 69 6e 20 53 51 4c 69 74 65 20  dules.in SQLite 
06e0: 6e 65 65 64 73 20 74 6f 20 63 6f 6d 6d 75 6e 69  needs to communi
06f0: 63 61 74 65 20 77 69 74 68 20 74 68 65 20 6f 70  cate with the op
0700: 65 72 61 74 69 6e 67 0a 73 79 73 74 65 6d 2c 20  erating.system, 
0710: 74 68 65 79 20 69 6e 76 6f 6b 65 20 6d 65 74 68  they invoke meth
0720: 6f 64 73 20 69 6e 20 74 68 65 20 56 46 53 2e 20  ods in the VFS. 
0730: 20 54 68 65 20 56 46 53 20 74 68 65 6e 20 69 6e   The VFS then in
0740: 76 6f 6b 65 73 20 74 68 65 0a 6f 70 65 72 61 74  vokes the.operat
0750: 69 6e 67 2d 73 70 65 63 69 66 69 63 20 63 6f 64  ing-specific cod
0760: 65 20 6e 65 65 64 65 64 20 74 6f 20 73 61 74 69  e needed to sati
0770: 73 66 79 20 74 68 65 20 72 65 71 75 65 73 74 2e  sfy the request.
0780: 0a 48 65 6e 63 65 2c 20 70 6f 72 74 69 6e 67 20  .Hence, porting 
0790: 53 51 4c 69 74 65 20 74 6f 20 61 20 6e 65 77 0a  SQLite to a new.
07a0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
07b0: 20 69 73 20 73 69 6d 70 6c 79 20 61 20 6d 61 74   is simply a mat
07c0: 74 65 72 20 6f 66 20 77 72 69 74 69 6e 67 20 61  ter of writing a
07d0: 20 6e 65 77 20 4f 53 20 69 6e 74 65 72 66 61 63   new OS interfac
07e0: 65 20 6c 61 79 65 72 0a 6f 72 20 22 56 46 53 22  e layer.or "VFS"
07f0: 2e 3c 2f 70 3e 0a 0a 3c 68 32 3e 32 2e 30 20 4d  .</p>..<h2>2.0 M
0800: 75 6c 74 69 70 6c 65 20 56 46 53 65 73 3c 2f 68  ultiple VFSes</h
0810: 32 3e 0a 0a 3c 70 3e 0a 54 68 65 20 73 74 61 6e  2>..<p>.The stan
0820: 64 61 72 64 20 53 51 4c 69 74 65 20 73 6f 75 72  dard SQLite sour
0830: 63 65 20 74 72 65 65 20 63 6f 6e 74 61 69 6e 73  ce tree contains
0840: 20 62 75 69 6c 74 2d 69 6e 20 56 46 53 65 73 20   built-in VFSes 
0850: 66 6f 72 20 6f 73 2f 32 2c 20 75 6e 69 78 2c 0a  for os/2, unix,.
0860: 61 6e 64 20 77 69 6e 64 6f 77 73 2e 20 20 41 6c  and windows.  Al
0870: 74 65 72 6e 61 74 69 76 65 20 56 46 53 65 73 20  ternative VFSes 
0880: 63 61 6e 20 62 65 0a 61 64 64 65 64 20 61 74 20  can be.added at 
0890: 73 74 61 72 74 2d 74 69 6d 65 20 6f 72 20 72 75  start-time or ru
08a0: 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 74 68 65  n-time using the
08b0: 0a 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  .[sqlite3_vfs_re
08c0: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
08d0: 61 63 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 4d  ace..</p>..<p>.M
08e0: 75 6c 74 69 70 6c 65 20 56 46 53 65 73 20 63 61  ultiple VFSes ca
08f0: 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
0900: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
0910: 2e 0a 45 61 63 68 20 56 46 53 20 68 61 73 20 61  ..Each VFS has a
0920: 20 75 6e 69 71 75 65 20 6e 61 6d 65 73 2e 0a 53   unique names..S
0930: 65 70 61 72 61 74 65 20 5b 64 61 74 61 62 61 73  eparate [databas
0940: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77  e connections] w
0950: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70  ithin the same p
0960: 72 6f 63 65 73 73 20 63 61 6e 20 62 65 20 75 73  rocess can be us
0970: 69 6e 67 0a 64 69 66 66 65 72 65 6e 74 20 56 46  ing.different VF
0980: 53 65 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  Ses at the same 
0990: 74 69 6d 65 2e 20 20 20 46 6f 72 20 74 68 61 74  time.   For that
09a0: 20 6d 61 74 74 65 72 2c 20 69 66 20 61 20 73 69   matter, if a si
09b0: 6e 67 6c 65 0a 64 61 74 61 62 61 73 65 20 63 6f  ngle.database co
09c0: 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 6d 75 6c  nnection has mul
09d0: 74 69 70 6c 65 20 64 61 74 61 62 61 73 65 20 66  tiple database f
09e0: 69 6c 65 73 20 6f 70 65 6e 20 75 73 69 6e 67 0a  iles open using.
09f0: 74 68 65 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d  the [ATTACH] com
0a00: 6d 61 6e 64 2c 20 74 68 65 6e 20 65 61 63 68 20  mand, then each 
0a10: 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
0a20: 65 20 6d 69 67 68 74 20 62 65 20 75 73 69 6e 67  e might be using
0a30: 20 61 0a 64 69 66 66 65 72 65 6e 74 20 56 46 53   a.different VFS
0a40: 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 55 6e 69 78  ..</p>..<p>.Unix
0a50: 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74   builds come wit
0a60: 68 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 65 73  h multiple VFSes
0a70: 20 62 75 69 6c 74 2d 69 6e 2e 20 20 54 68 65 20   built-in.  The 
0a80: 64 65 66 61 75 6c 74 20 56 46 53 0a 66 6f 72 20  default VFS.for 
0a90: 75 6e 69 78 20 69 73 20 63 61 6c 6c 65 64 20 22  unix is called "
0aa0: 75 6e 69 78 22 20 61 6e 64 20 69 73 20 74 68 65  unix" and is the
0ab0: 20 56 46 53 20 75 73 65 64 20 69 6e 20 61 6e 20   VFS used in an 
0ac0: 6f 76 65 72 77 68 65 6c 6d 69 6e 67 0a 6d 61 6a  overwhelming.maj
0ad0: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
0ae0: 74 69 6f 6e 73 2e 20 20 4f 74 68 65 72 20 56 46  tions.  Other VF
0af0: 53 65 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  Ses that can be 
0b00: 66 6f 75 6e 64 20 69 6e 20 75 6e 69 78 0a 6d 61  found in unix.ma
0b10: 79 20 69 6e 63 6c 75 64 65 3a 0a 3c 2f 70 3e 0a  y include:.</p>.
0b20: 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 3c 70 3e 3c 62 3e  .<ol>.<li><p><b>
0b30: 75 6e 69 78 2d 64 6f 74 66 69 6c 65 3c 2f 62 3e  unix-dotfile</b>
0b40: 20 2d 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65   - uses dot-file
0b50: 20 6c 6f 63 6b 69 6e 67 20 72 61 74 68 65 72 20   locking rather 
0b60: 74 68 61 6e 0a 20 20 20 20 20 20 20 20 20 20 50  than.          P
0b70: 4f 53 49 58 20 61 64 76 69 73 6f 72 79 20 6c 6f  OSIX advisory lo
0b80: 63 6b 73 2e 0a 3c 6c 69 3e 3c 70 3e 3c 62 3e 75  cks..<li><p><b>u
0b90: 6e 69 78 2d 65 78 63 6c 3c 2f 62 3e 20 2d 20 6f  nix-excl</b> - o
0ba0: 62 74 61 69 6e 73 20 61 6e 64 20 68 6f 6c 64 73  btains and holds
0bb0: 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
0bc0: 63 6b 20 6f 6e 0a 20 20 20 20 20 20 20 20 20 20  ck on.          
0bd0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2c 20  database files, 
0be0: 70 72 65 76 65 6e 74 69 6e 67 20 6f 74 68 65 72  preventing other
0bf0: 20 70 72 6f 63 65 73 73 65 73 20 66 72 6f 6d 20   processes from 
0c00: 61 63 63 65 73 73 69 6e 67 20 74 68 65 0a 20 20  accessing the.  
0c10: 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
0c20: 2e 20 20 41 6c 73 6f 20 6b 65 65 70 73 20 74 68  .  Also keeps th
0c30: 65 20 5b 77 61 6c 2d 69 6e 64 65 78 5d 20 69 6e  e [wal-index] in
0c40: 20 68 65 61 70 20 72 61 74 68 65 72 20 74 68 61   heap rather tha
0c50: 6e 20 69 6e 0a 20 20 20 20 20 20 20 20 20 20 73  n in.          s
0c60: 68 61 72 65 64 20 6d 65 6d 6f 72 79 2e 0a 3c 6c  hared memory..<l
0c70: 69 3e 3c 70 3e 3c 62 3e 75 6e 69 78 2d 6e 6f 6e  i><p><b>unix-non
0c80: 65 3c 2f 62 3e 20 2d 20 61 6c 6c 20 66 69 6c 65  e</b> - all file
0c90: 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69   locking operati
0ca0: 6f 6e 73 20 61 72 65 20 6e 6f 2d 6f 70 73 2e 0a  ons are no-ops..
0cb0: 3c 6c 69 3e 3c 70 3e 3c 62 3e 75 6e 69 78 2d 6e  <li><p><b>unix-n
0cc0: 61 6d 65 64 73 65 6d 3c 2f 62 3e 20 2d 20 75 73  amedsem</b> - us
0cd0: 65 73 20 6e 61 6d 65 64 20 73 65 6d 61 70 68 6f  es named semapho
0ce0: 72 65 73 20 66 6f 72 20 66 69 6c 65 20 6c 6f 63  res for file loc
0cf0: 6b 69 6e 67 2e 0a 20 20 20 20 20 20 20 56 58 57  king..       VXW
0d00: 6f 72 6b 73 20 6f 6e 6c 79 2e 0a 3c 2f 6f 6c 3e  orks only..</ol>
0d10: 0a 0a 3c 70 3e 0a 54 68 65 20 76 61 72 69 6f 75  ..<p>.The variou
0d20: 73 20 75 6e 69 78 20 56 46 53 65 73 20 64 69 66  s unix VFSes dif
0d30: 66 65 72 20 6f 6e 6c 79 20 69 6e 20 74 68 65 20  fer only in the 
0d40: 77 61 79 20 74 68 65 79 20 68 61 6e 64 6c 65 20  way they handle 
0d50: 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 2d 0a 74  file locking -.t
0d60: 68 65 79 20 73 68 61 72 65 20 6d 6f 73 74 20 6f  hey share most o
0d70: 66 20 74 68 65 69 72 20 69 6d 70 6c 65 6d 65 6e  f their implemen
0d80: 74 61 74 69 6f 6e 20 69 6e 20 63 6f 6d 6d 6f 6e  tation in common
0d90: 20 77 69 74 68 20 6f 6e 65 20 61 6e 6f 74 68 65   with one anothe
0da0: 72 20 61 6e 64 0a 61 72 65 20 61 6c 6c 20 6c 6f  r and.are all lo
0db0: 63 61 74 65 64 20 69 6e 20 74 68 65 20 73 61 6d  cated in the sam
0dc0: 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  e SQLite source 
0dd0: 66 69 6c 65 3a 20 20 0a 5b 68 74 74 70 3a 2f 2f  file:  .[http://
0de0: 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 73  www.sqlite.org/s
0df0: 72 63 2f 64 6f 63 2f 74 72 75 6e 6b 2f 73 72 63  rc/doc/trunk/src
0e00: 2f 6f 73 5f 75 6e 69 78 2e 63 20 7c 20 6f 73 5f  /os_unix.c | os_
0e10: 75 6e 69 78 2e 63 5d 2e 0a 4e 6f 74 65 20 74 68  unix.c]..Note th
0e20: 61 74 20 65 78 63 65 70 74 20 66 6f 72 20 22 75  at except for "u
0e30: 6e 69 78 22 20 61 6e 64 20 22 75 6e 69 78 2d 65  nix" and "unix-e
0e40: 78 63 6c 22 2c 20 74 68 65 20 76 61 72 69 6f 75  xcl", the variou
0e50: 73 20 75 6e 69 78 20 56 46 53 65 73 20 61 6c 6c  s unix VFSes all
0e60: 0a 75 73 65 20 69 6e 63 6f 6d 70 61 74 69 62 6c  .use incompatibl
0e70: 65 20 6c 6f 63 6b 69 6e 67 20 69 6d 70 6c 65 6d  e locking implem
0e80: 65 6e 74 61 74 69 6f 6e 73 2e 20 20 49 66 20 74  entations.  If t
0e90: 77 6f 20 70 72 6f 63 65 73 73 65 73 20 61 72 65  wo processes are
0ea0: 20 61 63 63 65 73 73 69 6e 67 0a 74 68 65 20 73   accessing.the s
0eb0: 61 6d 65 20 53 51 4c 69 74 65 20 64 61 74 61 62  ame SQLite datab
0ec0: 61 73 65 20 75 73 69 6e 67 20 64 69 66 66 65 72  ase using differ
0ed0: 65 6e 74 20 75 6e 69 78 20 56 46 53 65 73 2c 20  ent unix VFSes, 
0ee0: 74 68 65 79 20 6d 61 79 0a 6e 6f 74 20 73 65 65  they may.not see
0ef0: 20 65 61 63 68 20 6f 74 68 65 72 73 20 6c 6f 63   each others loc
0f00: 6b 73 20 61 6e 64 20 6d 61 79 20 65 6e 64 20 75  ks and may end u
0f10: 70 20 69 6e 74 65 72 66 65 72 69 6e 67 20 77 69  p interfering wi
0f20: 74 68 20 6f 6e 65 20 61 6e 6f 74 68 65 72 2c 0a  th one another,.
0f30: 72 65 73 75 6c 74 69 6e 67 20 69 6e 20 64 61 74  resulting in dat
0f40: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
0f50: 2e 20 20 54 68 65 20 22 75 6e 69 78 2d 6e 6f 6e  .  The "unix-non
0f60: 65 22 20 56 46 53 20 69 6e 20 70 61 72 74 69 63  e" VFS in partic
0f70: 75 6c 61 72 0a 64 6f 65 73 20 6e 6f 20 6c 6f 63  ular.does no loc
0f80: 6b 69 6e 67 20 61 74 20 61 6c 6c 20 61 6e 64 20  king at all and 
0f90: 77 69 6c 6c 20 65 61 73 69 6c 79 20 72 65 73 75  will easily resu
0fa0: 6c 74 20 69 6e 20 64 61 74 61 62 61 73 65 20 63  lt in database c
0fb0: 6f 72 72 75 70 74 69 6f 6e 20 69 66 0a 75 73 65  orruption if.use
0fc0: 64 20 62 79 20 74 77 6f 20 6f 72 20 6d 6f 72 65  d by two or more
0fd0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
0fe0: 74 69 6f 6e 73 20 61 74 20 74 68 65 20 73 61 6d  tions at the sam
0ff0: 65 20 74 69 6d 65 2e 0a 50 72 6f 67 72 61 6d 6d  e time..Programm
1000: 65 72 73 20 61 72 65 20 65 6e 63 6f 75 72 61 67  ers are encourag
1010: 65 64 20 74 6f 20 75 73 65 20 6f 6e 6c 79 20 22  ed to use only "
1020: 75 6e 69 78 22 20 6f 72 20 22 75 6e 69 78 2d 65  unix" or "unix-e
1030: 78 63 6c 22 20 75 6e 6c 65 73 73 0a 74 68 65 72  xcl" unless.ther
1040: 65 20 69 73 20 61 20 63 6f 6d 70 65 6c 6c 69 6e  e is a compellin
1050: 67 20 72 65 61 73 6f 6e 20 74 6f 20 64 6f 20 6f  g reason to do o
1060: 74 68 65 72 77 69 73 65 2e 0a 3c 2f 70 3e 0a 0a  therwise..</p>..
1070: 3c 68 32 3e 32 2e 31 20 53 70 65 63 69 66 79 69  <h2>2.1 Specifyi
1080: 6e 67 20 57 68 69 63 68 20 56 46 53 20 54 6f 20  ng Which VFS To 
1090: 55 73 65 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 54 68  Use</h2>..<p>.Th
10a0: 65 72 65 20 69 73 20 61 6c 77 61 79 73 20 6f 6e  ere is always on
10b0: 65 20 56 46 53 20 77 68 69 63 68 20 69 73 20 74  e VFS which is t
10c0: 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2e 20  he default VFS. 
10d0: 20 4f 6e 20 75 6e 69 78 20 73 79 73 74 65 6d 73   On unix systems
10e0: 2c 0a 74 68 65 20 22 75 6e 69 78 22 20 56 46 53  ,.the "unix" VFS
10f0: 20 63 6f 6d 65 73 20 75 70 20 61 73 20 74 68 65   comes up as the
1100: 20 64 65 66 61 75 6c 74 20 61 6e 64 20 6f 6e 20   default and on 
1110: 77 69 6e 64 6f 77 73 20 69 74 20 69 73 20 22 77  windows it is "w
1120: 69 6e 33 32 22 2e 0a 49 66 20 6e 6f 20 6f 74 68  in32"..If no oth
1130: 65 72 20 61 63 74 69 6f 6e 73 20 61 72 65 20 74  er actions are t
1140: 61 6b 65 6e 2c 20 6e 65 77 20 64 61 74 61 62 61  aken, new databa
1150: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 77  se connections w
1160: 69 6c 6c 20 6d 61 6b 65 20 75 73 65 0a 6f 66 20  ill make use.of 
1170: 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2e  the default VFS.
1180: 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 64  .</p>..<p>.The d
1190: 65 66 61 75 6c 74 20 56 46 53 20 63 61 6e 20 62  efault VFS can b
11a0: 65 20 63 68 61 6e 67 65 64 20 62 79 20 72 65 67  e changed by reg
11b0: 69 73 74 65 72 69 6e 67 20 6f 72 20 72 65 2d 72  istering or re-r
11c0: 65 67 69 73 74 65 72 69 6e 67 20 74 68 65 0a 56  egistering the.V
11d0: 46 53 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  FS using the [sq
11e0: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
11f0: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
1200: 77 69 74 68 20 61 20 73 65 63 6f 6e 64 20 70 61  with a second pa
1210: 72 61 6d 65 74 65 72 0a 6f 66 20 31 2e 20 20 48  rameter.of 1.  H
1220: 65 6e 63 65 2c 20 69 66 20 61 20 28 75 6e 69 78  ence, if a (unix
1230: 29 20 70 72 6f 63 65 73 73 20 74 6f 20 61 6c 77  ) process to alw
1240: 61 79 73 20 75 73 65 20 74 68 65 20 22 75 6e 69  ays use the "uni
1250: 78 2d 6e 6f 6c 6f 63 6b 22 20 56 46 53 20 0a 69  x-nolock" VFS .i
1260: 6e 20 70 6c 61 63 65 20 6f 66 20 22 75 6e 69 78  n place of "unix
1270: 22 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ", the following
1280: 20 63 6f 64 65 20 77 6f 75 6c 64 20 77 6f 72 6b   code would work
1290: 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  :.</p>..<blockqu
12a0: 6f 74 65 3e 3c 70 72 65 3e 0a 73 71 6c 69 74 65  ote><pre>.sqlite
12b0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 73  3_vfs_register(s
12c0: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
12d0: 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 29 2c 20  "unix-nolock"), 
12e0: 31 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  1);.</pre></bloc
12f0: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 41 6e 20  kquote>..<p>.An 
1300: 61 6c 74 65 72 6e 61 74 65 20 56 46 53 20 63 61  alternate VFS ca
1310: 6e 20 61 6c 73 6f 20 62 65 20 73 70 65 63 69 66  n also be specif
1320: 69 65 64 20 61 73 20 74 68 65 20 34 74 68 20 70  ied as the 4th p
1330: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
1340: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1350: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 20 20 46  ()] function.  F
1360: 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 3c 2f 70 3e  or example:.</p>
1370: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
1380: 72 65 3e 0a 69 6e 74 20 72 63 20 3d 20 73 71 6c  re>.int rc = sql
1390: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 22 64 65  ite3_open_v2("de
13a0: 6d 6f 2e 64 62 22 2c 20 26 64 62 2c 20 53 51 4c  mo.db", &db, SQL
13b0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
13c0: 54 45 2c 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b  TE, "unix-nolock
13d0: 22 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  ");.</pre></bloc
13e0: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 46 69 6e  kquote>..<p>.Fin
13f0: 61 6c 6c 79 2c 20 69 66 20 5b 55 52 49 20 66 69  ally, if [URI fi
1400: 6c 65 6e 61 6d 65 73 5d 20 68 61 76 65 20 62 65  lenames] have be
1410: 65 6e 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 6e  en enabled, then
1420: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
1430: 0a 56 46 53 20 63 61 6e 20 62 65 20 73 70 65 63  .VFS can be spec
1440: 69 66 69 65 64 20 75 73 69 6e 67 20 74 68 65 20  ified using the 
1450: 22 76 66 73 3d 22 20 70 61 72 61 6d 65 74 65 72  "vfs=" parameter
1460: 20 6f 6e 20 74 68 65 20 55 52 49 2e 20 20 54 68   on the URI.  Th
1470: 69 73 20 74 65 63 68 6e 69 71 75 65 0a 77 6f 72  is technique.wor
1480: 6b 73 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ks with [sqlite3
1490: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
14a0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 5b 73  e3_open16()], [s
14b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
14c0: 5d 2c 20 61 6e 64 0a 77 68 65 6e 20 61 20 6e 65  ], and.when a ne
14d0: 77 20 64 61 74 61 62 61 73 65 20 69 73 20 5b 41  w database is [A
14e0: 54 54 41 43 48 5d 2d 65 64 20 74 6f 20 61 6e 20  TTACH]-ed to an 
14f0: 65 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73  existing databas
1500: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 46 6f  e connection..Fo
1510: 72 20 65 78 61 6d 70 6c 65 3a 0a 3c 2f 70 3e 0a  r example:.</p>.
1520: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72  .<blockquote><pr
1530: 65 3e 0a 41 54 54 41 43 48 20 27 66 69 6c 65 3a  e>.ATTACH 'file:
1540: 64 65 6d 6f 32 2e 64 62 3f 76 66 73 3d 75 6e 69  demo2.db?vfs=uni
1550: 78 2d 6e 6f 6e 65 27 20 41 53 20 64 65 6d 6f 32  x-none' AS demo2
1560: 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  ;.</pre></blockq
1570: 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65 20 56  uote>..<p>.The V
1580: 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
1590: 61 20 55 52 49 20 68 61 73 20 74 68 65 20 68 69  a URI has the hi
15a0: 67 68 65 73 74 20 70 72 69 6f 72 69 74 79 2e 20  ghest priority. 
15b0: 20 41 66 74 65 72 20 74 68 61 74 20 63 6f 6d 65   After that come
15c0: 73 0a 61 20 56 46 53 20 73 70 65 63 69 66 69 65  s.a VFS specifie
15d0: 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
15e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
15f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
1600: 20 20 54 68 65 0a 64 65 66 61 75 6c 74 20 56 46    The.default VF
1610: 53 20 69 73 20 75 73 65 64 20 69 66 20 6e 6f 20  S is used if no 
1620: 56 46 53 20 69 73 20 73 70 65 63 69 66 69 65 64  VFS is specified
1630: 20 6f 74 68 65 72 77 69 73 65 2e 0a 3c 2f 70 3e   otherwise..</p>
1640: 0a 0a 3c 68 32 3e 32 2e 32 20 56 46 53 20 53 68  ..<h2>2.2 VFS Sh
1650: 69 6d 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 46 72  ims</h2>..<p>.Fr
1660: 6f 6d 20 74 68 65 20 70 6f 69 6e 74 20 6f 66 20  om the point of 
1670: 76 69 65 77 20 6f 66 20 74 68 65 20 75 70 70 65  view of the uppe
1680: 72 73 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65  rs layers of the
1690: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 2c 20 65   SQLite stack, e
16a0: 61 63 68 0a 6f 70 65 6e 20 64 61 74 61 62 61 73  ach.open databas
16b0: 65 20 66 69 6c 65 20 75 73 65 73 20 65 78 61 63  e file uses exac
16c0: 74 6c 79 20 6f 6e 65 20 56 46 53 2e 0a 42 75 74  tly one VFS..But
16d0: 20 69 6e 20 70 72 61 63 74 69 63 65 2c 20 61 20   in practice, a 
16e0: 70 61 72 74 69 63 75 6c 61 72 20 56 46 53 20 6d  particular VFS m
16f0: 69 67 68 74 0a 6a 75 73 74 20 62 65 20 61 20 74  ight.just be a t
1700: 68 69 6e 20 77 72 61 70 70 65 72 20 61 72 6f 75  hin wrapper arou
1710: 6e 64 20 61 6e 6f 74 68 65 72 20 56 46 53 20 74  nd another VFS t
1720: 68 61 74 20 64 6f 65 73 20 74 68 65 20 72 65 61  hat does the rea
1730: 6c 20 77 6f 72 6b 2e 0a 57 65 20 63 61 6c 6c 20  l work..We call 
1740: 61 20 77 72 61 70 70 65 72 20 56 46 53 20 61 20  a wrapper VFS a 
1750: 22 73 68 69 6d 22 2e 0a 3c 2f 70 3e 0a 0a 3c 70  "shim"..</p>..<p
1760: 3e 0a 41 20 73 69 6d 70 6c 65 20 65 78 61 6d 70  >.A simple examp
1770: 6c 65 20 6f 66 20 61 20 73 68 69 6d 20 69 73 20  le of a shim is 
1780: 74 68 65 20 22 76 66 73 74 72 61 63 65 22 20 56  the "vfstrace" V
1790: 46 53 2e 20 20 54 68 69 73 20 69 73 20 61 20 56  FS.  This is a V
17a0: 46 53 0a 28 69 6d 70 6c 65 6d 65 6e 74 65 64 20  FS.(implemented 
17b0: 69 6e 20 74 68 65 20 0a 5b 68 74 74 70 3a 2f 2f  in the .[http://
17c0: 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 73  www.sqlite.org/s
17d0: 72 63 2f 64 6f 63 2f 74 72 75 6e 6b 2f 73 72 63  rc/doc/trunk/src
17e0: 2f 74 65 73 74 5f 76 66 73 74 72 61 63 65 2e 63  /test_vfstrace.c
17f0: 20 7c 20 74 65 73 74 5f 76 66 73 74 72 61 63 65   | test_vfstrace
1800: 2e 63 5d 0a 73 6f 75 72 63 65 20 66 69 6c 65 29  .c].source file)
1810: 20 74 68 61 74 20 77 72 69 74 65 73 20 61 20 6d   that writes a m
1820: 65 73 73 61 67 65 20 61 73 73 6f 63 69 61 74 65  essage associate
1830: 64 20 77 69 74 68 20 65 61 63 68 20 56 46 53 20  d with each VFS 
1840: 6d 65 74 68 6f 64 20 63 61 6c 6c 0a 69 6e 74 6f  method call.into
1850: 20 61 20 6c 6f 67 20 66 69 6c 65 2c 20 74 68 65   a log file, the
1860: 6e 20 70 61 73 73 65 73 20 63 6f 6e 74 72 6f 6c  n passes control
1870: 20 6f 66 66 20 74 6f 20 61 6e 6f 74 68 65 72 20   off to another 
1880: 56 46 53 20 74 6f 20 64 6f 20 74 68 65 20 61 63  VFS to do the ac
1890: 74 75 61 6c 0a 77 6f 72 6b 2e 0a 3c 2f 70 3e 0a  tual.work..</p>.
18a0: 0a 3c 68 32 3e 32 2e 33 20 4f 74 68 65 72 20 45  .<h2>2.3 Other E
18b0: 78 61 6d 70 6c 65 20 56 46 53 65 73 3c 2f 68 32  xample VFSes</h2
18c0: 3e 0a 0a 3c 70 3e 0a 54 68 65 20 66 6f 6c 6c 6f  >..<p>.The follo
18d0: 77 69 6e 67 20 61 72 65 20 6f 74 68 65 72 20 56  wing are other V
18e0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
18f0: 6e 73 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ns available in 
1900: 74 68 65 20 70 75 62 6c 69 63 0a 53 51 4c 69 74  the public.SQLit
1910: 65 20 73 6f 75 72 63 65 20 74 72 65 65 3a 0a 3c  e source tree:.<
1920: 2f 70 3e 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 3c 70  /p>..<ul>.<li><p
1930: 3e 0a 5b 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71  >.[http://www.sq
1940: 6c 69 74 65 2e 6f 72 67 2f 73 72 63 2f 64 6f 63  lite.org/src/doc
1950: 2f 74 72 75 6e 6b 2f 73 72 63 2f 74 65 73 74 5f  /trunk/src/test_
1960: 64 65 6d 6f 76 66 73 2e 63 20 7c 20 74 65 73 74  demovfs.c | test
1970: 5f 64 65 6d 6f 76 66 73 2e 63 5d 20 2d 20 0a 54  _demovfs.c] - .T
1980: 68 69 73 20 66 69 6c 65 20 69 6d 70 6c 65 6d 65  his file impleme
1990: 6e 74 73 20 61 20 76 65 72 79 20 73 69 6d 70 6c  nts a very simpl
19a0: 65 20 56 46 53 20 6e 61 6d 65 64 20 22 64 65 6d  e VFS named "dem
19b0: 6f 22 20 74 68 61 74 20 75 73 73 20 50 4f 53 49  o" that uss POSI
19c0: 58 20 0a 66 75 6e 63 74 69 6f 6e 73 20 73 75 63  X .functions suc
19d0: 68 20 61 73 0a 6f 70 65 6e 28 29 2c 20 72 65 61  h as.open(), rea
19e0: 64 28 29 2c 20 77 72 69 74 65 28 29 2c 20 66 73  d(), write(), fs
19f0: 79 6e 63 28 29 2c 20 63 6c 6f 73 65 28 29 2c 20  ync(), close(), 
1a00: 66 73 79 6e 63 28 29 2c 20 73 6c 65 65 70 28 29  fsync(), sleep()
1a10: 2c 20 74 69 6d 65 28 29 2c 0a 61 6e 64 20 73 6f  , time(),.and so
1a20: 20 66 6f 72 74 68 2e 20 20 54 68 69 73 20 56 46   forth.  This VF
1a30: 53 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20  S only works on 
1a40: 75 6e 69 78 20 73 79 73 74 65 6d 73 2e 20 20 42  unix systems.  B
1a50: 75 74 20 69 74 20 69 73 20 6e 6f 74 0a 69 6e 74  ut it is not.int
1a60: 65 6e 64 65 64 20 61 73 20 61 20 72 65 70 6c 61  ended as a repla
1a70: 63 65 6d 65 6e 74 20 66 6f 72 20 74 68 65 20 73  cement for the s
1a80: 74 61 6e 64 61 72 64 20 22 75 6e 69 78 22 20 56  tandard "unix" V
1a90: 46 53 20 75 73 65 64 20 62 79 20 64 65 66 61 75  FS used by defau
1aa0: 6c 74 0a 6f 6e 20 75 6e 69 78 20 70 6c 61 74 66  lt.on unix platf
1ab0: 6f 72 6d 73 2e 20 20 54 68 65 20 22 64 65 6d 6f  orms.  The "demo
1ac0: 22 20 56 46 53 20 69 73 20 64 65 6c 69 62 65 72  " VFS is deliber
1ad0: 61 74 65 6c 79 20 6b 65 70 74 20 76 65 72 79 20  ately kept very 
1ae0: 73 69 6d 70 6c 65 0a 73 6f 20 74 68 61 74 20 69  simple.so that i
1af0: 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  t can be used as
1b00: 20 61 20 6c 65 61 72 6e 69 6e 67 20 61 69 64 20   a learning aid 
1b10: 6f 72 20 61 73 20 74 65 6d 70 6c 61 74 65 20 66  or as template f
1b20: 6f 72 20 62 75 69 6c 64 69 6e 67 0a 6f 74 68 65  or building.othe
1b30: 72 20 56 46 53 65 73 20 6f 72 20 66 6f 72 20 70  r VFSes or for p
1b40: 6f 72 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f  orting SQLite to
1b50: 20 6e 65 77 20 6f 70 65 72 61 74 69 6e 67 20 73   new operating s
1b60: 79 73 74 65 6d 73 2e 0a 0a 3c 6c 69 3e 3c 70 3e  ystems...<li><p>
1b70: 0a 5b 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c  .[http://www.sql
1b80: 69 74 65 2e 6f 72 67 2f 73 72 63 2f 64 6f 63 2f  ite.org/src/doc/
1b90: 74 72 75 6e 6b 2f 73 72 63 2f 74 65 73 74 5f 71  trunk/src/test_q
1ba0: 75 6f 74 61 2e 63 20 7c 20 74 65 73 74 5f 71 75  uota.c | test_qu
1bb0: 6f 74 61 2e 63 5d 20 2d 20 0a 54 68 69 73 20 66  ota.c] - .This f
1bc0: 69 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 61  ile implements a
1bd0: 20 73 68 69 6d 20 63 61 6c 6c 65 64 20 22 71 75   shim called "qu
1be0: 6f 74 61 22 20 74 68 61 74 20 65 6e 66 6f 72 63  ota" that enforc
1bf0: 65 73 20 63 75 6d 75 6c 61 74 69 76 65 0a 66 69  es cumulative.fi
1c00: 6c 65 20 73 69 7a 65 20 6c 69 6d 69 74 73 20 6f  le size limits o
1c10: 6e 20 61 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  n a collection o
1c20: 66 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  f database files
1c30: 2e 20 20 41 6e 20 61 75 78 69 6c 69 61 72 79 0a  .  An auxiliary.
1c40: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
1c50: 64 20 74 6f 20 64 65 66 69 6e 65 20 22 71 75 6f  d to define "quo
1c60: 74 65 20 67 72 6f 75 70 73 22 2e 20 20 41 20 71  te groups".  A q
1c70: 75 6f 74 61 20 67 72 6f 75 70 20 69 73 20 61 0a  uota group is a.
1c80: 73 65 74 20 6f 66 20 66 69 6c 65 73 20 28 64 61  set of files (da
1c90: 74 61 62 61 73 65 20 66 69 6c 65 73 2c 20 6a 6f  tabase files, jo
1ca0: 75 72 6e 61 6c 73 2c 20 61 6e 64 20 74 65 6d 70  urnals, and temp
1cb0: 6f 72 61 72 79 20 66 69 6c 65 73 29 20 77 68 6f  orary files) who
1cc0: 73 65 0a 6e 61 6d 65 73 20 61 6c 6c 20 6d 61 74  se.names all mat
1cd0: 63 68 20 61 20 5b 47 4c 4f 42 5d 20 70 61 74 74  ch a [GLOB] patt
1ce0: 65 72 6e 2e 20 20 54 68 65 20 73 75 6d 20 6f 66  ern.  The sum of
1cf0: 20 74 68 65 20 73 69 7a 65 73 20 6f 66 20 61 6c   the sizes of al
1d00: 6c 20 66 69 6c 65 73 0a 69 6e 20 65 61 63 68 20  l files.in each 
1d10: 71 75 6f 74 61 20 67 72 6f 75 70 20 69 73 20 74  quota group is t
1d20: 72 61 63 6b 65 64 2c 20 61 6e 64 20 69 66 20 74  racked, and if t
1d30: 68 61 74 20 73 75 6d 20 65 78 63 65 65 64 73 20  hat sum exceeds 
1d40: 61 20 74 68 72 65 73 68 6f 6c 64 0a 64 65 66 69  a threshold.defi
1d50: 6e 65 64 20 66 6f 72 20 74 68 65 20 71 75 6f 74  ned for the quot
1d60: 61 20 67 72 6f 75 70 2c 20 61 20 63 61 6c 6c 62  a group, a callb
1d70: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ack function is 
1d80: 69 6e 76 6f 6b 65 64 2e 20 20 54 68 61 74 0a 63  invoked.  That.c
1d90: 61 6c 6c 62 61 63 6b 20 63 61 6e 20 65 69 74 68  allback can eith
1da0: 65 72 20 69 6e 63 72 65 61 73 65 20 74 68 65 20  er increase the 
1db0: 74 68 72 65 73 68 6f 6c 64 20 6f 72 20 63 61 75  threshold or cau
1dc0: 73 65 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  se the operation
1dd0: 0a 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65  .that would have
1de0: 20 65 78 63 65 65 64 65 64 20 74 68 65 20 71 75   exceeded the qu
1df0: 6f 74 61 20 74 6f 20 66 61 69 6c 20 77 69 74 68  ota to fail with
1e00: 20 61 6e 20 0a 5b 53 51 4c 49 54 45 5f 46 55 4c   an .[SQLITE_FUL
1e10: 4c 5d 20 65 72 72 6f 72 2e 20 20 4f 6e 65 20 6f  L] error.  One o
1e20: 66 20 74 68 65 20 75 73 65 73 20 6f 66 20 74 68  f the uses of th
1e30: 69 73 20 73 68 69 6d 20 69 73 20 75 73 65 64 20  is shim is used 
1e40: 74 6f 20 65 6e 66 6f 72 63 65 20 0a 72 65 73 6f  to enforce .reso
1e50: 75 72 63 65 20 6c 69 6d 69 74 73 20 6f 6e 20 61  urce limits on a
1e60: 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 62  pplication datab
1e70: 61 73 65 73 20 69 6e 20 46 69 72 65 66 6f 78 2e  ases in Firefox.
1e80: 0a 0a 3c 6c 69 3e 3c 70 3e 0a 5b 68 74 74 70 3a  ..<li><p>.[http:
1e90: 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67  //www.sqlite.org
1ea0: 2f 73 72 63 2f 64 6f 63 2f 74 72 75 6e 6b 2f 73  /src/doc/trunk/s
1eb0: 72 63 2f 74 65 73 74 5f 6d 75 6c 74 69 70 6c 65  rc/test_multiple
1ec0: 78 2e 63 20 7c 20 74 65 73 74 5f 6d 75 6c 74 69  x.c | test_multi
1ed0: 70 6c 65 78 2e 63 5d 20 2d 20 0a 54 68 69 73 20  plex.c] - .This 
1ee0: 66 69 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  file implements 
1ef0: 61 20 73 68 69 6d 20 74 68 61 74 20 61 6c 6c 6f  a shim that allo
1f00: 77 73 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ws database file
1f10: 73 20 74 6f 20 65 78 63 65 65 64 20 74 68 65 0a  s to exceed the.
1f20: 6d 61 78 69 6d 75 6d 20 66 69 6c 65 20 73 69 7a  maximum file siz
1f30: 65 20 6f 66 20 74 68 65 20 75 6e 64 65 72 6c 79  e of the underly
1f40: 69 6e 67 20 66 69 6c 65 73 79 73 74 65 6d 2e 20  ing filesystem. 
1f50: 20 54 68 69 73 20 73 68 69 6d 20 70 72 65 73 65   This shim prese
1f60: 6e 74 73 0a 61 6e 20 69 6e 74 65 72 66 61 63 65  nts.an interface
1f70: 20 74 6f 20 74 68 65 20 75 70 70 65 72 20 73 69   to the upper si
1f80: 78 20 6c 61 79 65 72 73 20 6f 66 20 53 51 4c 69  x layers of SQLi
1f90: 74 65 20 74 68 61 74 20 6d 61 6b 65 73 20 69 74  te that makes it
1fa0: 20 6c 6f 6f 6b 20 6c 69 6b 65 0a 76 65 72 79 20   look like.very 
1fb0: 6c 61 72 67 65 20 66 69 6c 65 73 20 61 72 65 20  large files are 
1fc0: 62 65 69 6e 67 20 75 73 65 64 2c 20 77 68 65 6e  being used, when
1fd0: 20 69 6e 20 72 65 61 6c 69 74 79 20 65 61 63 68   in reality each
1fe0: 20 73 75 63 68 20 6c 61 72 67 65 20 66 69 6c 65   such large file
1ff0: 0a 69 73 20 73 70 6c 69 74 20 75 70 20 69 6e 74  .is split up int
2000: 6f 20 6d 61 6e 79 20 73 6d 61 6c 6c 65 72 20 66  o many smaller f
2010: 69 6c 65 73 20 6f 6e 20 74 68 65 20 75 6e 64 65  iles on the unde
2020: 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 2e 0a 54  rlying system..T
2030: 68 69 73 20 73 68 69 6d 20 68 61 73 20 62 65 65  his shim has bee
2040: 6e 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  n used, for exam
2050: 70 6c 65 2c 20 74 6f 20 61 6c 6c 6f 77 20 64 61  ple, to allow da
2060: 74 61 62 61 73 65 73 20 74 6f 20 67 72 6f 77 0a  tabases to grow.
2070: 6c 61 72 67 65 72 20 74 68 61 6e 20 32 20 67 69  larger than 2 gi
2080: 62 69 62 79 74 65 73 20 6f 6e 20 46 41 54 31 36  bibytes on FAT16
2090: 20 66 69 6c 65 73 79 73 74 65 6d 73 2e 0a 0a 3c   filesystems...<
20a0: 6c 69 3e 3c 70 3e 0a 5b 68 74 74 70 3a 2f 2f 77  li><p>.[http://w
20b0: 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 73 72  ww.sqlite.org/sr
20c0: 63 2f 64 6f 63 2f 74 72 75 6e 6b 2f 73 72 63 2f  c/doc/trunk/src/
20d0: 74 65 73 74 5f 6f 6e 65 66 69 6c 65 2e 63 20 7c  test_onefile.c |
20e0: 20 74 65 73 74 5f 6f 6e 65 66 69 6c 65 2e 63 5d   test_onefile.c]
20f0: 20 2d 20 0a 54 68 69 73 20 66 69 6c 65 20 69 6d   - .This file im
2100: 70 6c 65 6d 65 6e 74 73 20 61 20 64 65 6d 6f 6e  plements a demon
2110: 73 74 72 61 74 69 6f 6e 20 56 46 53 20 6e 61 6d  stration VFS nam
2120: 65 64 20 22 66 73 22 20 74 68 61 74 20 73 68 6f  ed "fs" that sho
2130: 77 73 20 68 6f 77 20 53 51 4c 69 74 65 20 0a 63  ws how SQLite .c
2140: 61 6e 20 62 65 20 75 73 65 64 20 6f 6e 20 61 6e  an be used on an
2150: 20 65 6d 62 65 64 64 65 64 20 64 65 76 69 63 65   embedded device
2160: 20 74 68 61 74 20 6c 61 63 6b 73 20 61 20 66 69   that lacks a fi
2170: 6c 65 73 79 73 74 65 6d 2e 20 20 43 6f 6e 74 65  lesystem.  Conte
2180: 6e 74 20 69 73 0a 77 72 69 74 74 65 6e 20 64 69  nt is.written di
2190: 72 65 63 74 6c 79 20 74 6f 20 74 68 65 20 75 6e  rectly to the un
21a0: 64 65 72 6c 79 69 6e 67 20 6d 65 64 69 61 2e 20  derlying media. 
21b0: 20 41 20 56 46 53 20 64 65 72 69 76 65 64 20 66   A VFS derived f
21c0: 72 6f 6d 20 74 68 69 73 0a 64 65 6d 6f 6e 73 74  rom this.demonst
21d0: 72 61 74 69 6f 6e 20 63 6f 64 65 20 63 6f 75 6c  ration code coul
21e0: 64 20 62 65 20 75 73 65 64 20 62 79 20 61 20 67  d be used by a g
21f0: 61 64 67 65 74 20 77 69 74 68 20 61 20 6c 69 6d  adget with a lim
2200: 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66 0a 66  ited amount of.f
2210: 6c 61 73 68 20 6d 65 6d 6f 72 79 20 74 6f 20 6d  lash memory to m
2220: 61 6b 65 20 53 51 4c 69 74 65 20 62 65 68 61 76  ake SQLite behav
2230: 65 20 61 73 20 74 68 65 20 66 69 6c 65 73 79 73  e as the filesys
2240: 74 65 6d 20 66 6f 72 20 74 68 65 20 66 6c 61 73  tem for the flas
2250: 68 20 6d 65 6d 6f 72 79 0a 6f 6e 20 74 68 65 20  h memory.on the 
2260: 64 65 76 69 63 65 2e 0a 0a 3c 6c 69 3e 3c 70 3e  device...<li><p>
2270: 0a 5b 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c  .[http://www.sql
2280: 69 74 65 2e 6f 72 67 2f 73 72 63 2f 64 6f 63 2f  ite.org/src/doc/
2290: 74 72 75 6e 6b 2f 73 72 63 2f 74 65 73 74 5f 6a  trunk/src/test_j
22a0: 6f 75 72 6e 61 6c 2e 63 20 7c 20 74 65 73 74 5f  ournal.c | test_
22b0: 6a 6f 75 72 6e 61 6c 2e 63 5d 20 2d 20 0a 54 68  journal.c] - .Th
22c0: 69 73 20 66 69 6c 65 20 69 6d 70 6c 65 6d 65 6e  is file implemen
22d0: 74 73 20 61 20 73 68 69 6d 20 75 73 65 64 20 64  ts a shim used d
22e0: 75 72 69 6e 67 20 53 51 4c 69 74 65 20 74 65 73  uring SQLite tes
22f0: 74 69 6e 67 20 74 68 61 74 20 76 65 72 69 66 69  ting that verifi
2300: 65 73 20 74 68 61 74 0a 74 68 65 20 64 61 74 61  es that.the data
2310: 62 61 73 65 20 61 6e 64 20 72 6f 6c 6c 62 61 63  base and rollbac
2320: 6b 20 6a 6f 75 72 6e 61 6c 20 61 72 65 20 77 72  k journal are wr
2330: 69 74 74 65 6e 20 69 6e 20 74 68 65 20 63 6f 72  itten in the cor
2340: 72 65 63 74 20 6f 72 64 65 72 20 61 6e 64 0a 61  rect order and.a
2350: 72 65 20 22 73 79 6e 63 65 64 22 20 61 74 20 61  re "synced" at a
2360: 70 70 72 6f 70 72 69 61 74 65 20 74 69 6d 65 73  ppropriate times
2370: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 67 75 61   in order to gua
2380: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20  rantee that the 
2390: 64 61 74 61 62 61 73 65 0a 63 61 6e 20 72 65 63  database.can rec
23a0: 6f 76 65 72 20 66 72 6f 6d 20 61 20 70 6f 77 65  over from a powe
23b0: 72 20 6c 6f 73 65 20 61 72 65 20 68 61 72 64 20  r lose are hard 
23c0: 72 65 73 65 74 20 61 74 20 61 6e 79 20 74 69 6d  reset at any tim
23d0: 65 2e 20 20 54 68 65 20 73 68 69 6d 0a 63 68 65  e.  The shim.che
23e0: 63 6b 73 20 73 65 76 65 72 61 6c 20 69 6e 76 61  cks several inva
23f0: 72 69 61 6e 74 73 20 6f 6e 20 74 68 65 20 6f 70  riants on the op
2400: 65 72 61 74 69 6f 6e 20 6f 66 20 64 61 74 61 62  eration of datab
2410: 61 73 65 73 20 61 6e 64 20 72 6f 6c 6c 62 61 63  ases and rollbac
2420: 6b 0a 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 72  k.journals and r
2430: 61 69 73 65 73 20 65 78 63 65 70 74 69 6f 6e 73  aises exceptions
2440: 20 69 66 20 61 6e 79 20 6f 66 20 74 68 6f 73 65   if any of those
2450: 20 69 6e 76 61 72 69 61 6e 74 73 20 61 72 65 20   invariants are 
2460: 76 69 6f 6c 61 74 65 64 2e 0a 54 68 65 73 65 20  violated..These 
2470: 69 6e 76 61 72 69 61 6e 74 73 2c 20 69 6e 20 74  invariants, in t
2480: 75 72 6e 2c 20 61 73 73 75 72 65 20 74 68 61 74  urn, assure that
2490: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
24a0: 20 61 6c 77 61 79 73 20 72 65 63 6f 76 65 72 61   always recovera
24b0: 62 6c 65 2e 0a 52 75 6e 6e 69 6e 67 20 61 20 6c  ble..Running a l
24c0: 61 72 67 65 20 73 75 69 74 65 20 6f 66 20 74 65  arge suite of te
24d0: 73 74 20 63 61 73 65 73 20 75 73 69 6e 67 20 74  st cases using t
24e0: 68 69 73 20 73 68 69 6d 20 70 72 6f 76 69 64 65  his shim provide
24f0: 73 20 61 64 64 65 64 0a 61 73 73 75 72 61 6e 63  s added.assuranc
2500: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 64 61  e that SQLite da
2510: 74 61 62 61 73 65 73 20 77 69 6c 6c 20 6e 6f 74  tabases will not
2520: 20 62 65 20 64 61 6d 61 67 65 64 20 62 79 20 75   be damaged by u
2530: 6e 65 78 70 65 63 74 65 64 0a 70 6f 77 65 72 20  nexpected.power 
2540: 66 61 69 6c 75 72 65 73 20 6f 72 20 64 65 76 69  failures or devi
2550: 63 65 20 72 65 73 65 74 73 2e 0a 0a 3c 6c 69 3e  ce resets...<li>
2560: 3c 70 3e 0a 5b 68 74 74 70 3a 2f 2f 77 77 77 2e  <p>.[http://www.
2570: 73 71 6c 69 74 65 2e 6f 72 67 2f 73 72 63 2f 64  sqlite.org/src/d
2580: 6f 63 2f 74 72 75 6e 6b 2f 73 72 63 2f 74 65 73  oc/trunk/src/tes
2590: 74 5f 76 66 73 2e 63 20 7c 20 74 65 73 74 5f 76  t_vfs.c | test_v
25a0: 66 73 2e 63 5d 20 2d 20 0a 54 68 69 73 20 66 69  fs.c] - .This fi
25b0: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 61 20  le implements a 
25c0: 73 68 69 6d 20 74 68 61 74 20 63 61 6e 20 62 65  shim that can be
25d0: 20 75 73 65 64 20 74 6f 20 73 69 6d 75 6c 61 74   used to simulat
25e0: 65 20 66 69 6c 65 73 79 73 74 65 6d 20 66 61 75  e filesystem fau
25f0: 6c 74 73 2e 0a 54 68 69 73 20 73 68 69 6d 20 69  lts..This shim i
2600: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
2610: 73 74 69 6e 67 20 74 6f 20 76 65 72 69 66 79 20  sting to verify 
2620: 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 73 70  that SQLite resp
2630: 6f 6e 73 65 73 20 73 61 6e 65 6c 79 0a 74 6f 20  onses sanely.to 
2640: 68 61 72 64 77 61 72 65 20 6d 61 6c 66 75 6e 63  hardware malfunc
2650: 74 69 6f 6e 73 20 6f 72 20 74 6f 20 6f 74 68 65  tions or to othe
2660: 72 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  r error conditio
2670: 6e 73 20 73 75 63 68 20 61 73 20 72 75 6e 6e 69  ns such as runni
2680: 6e 67 20 6f 75 74 0a 6f 66 20 66 69 6c 65 73 79  ng out.of filesy
2690: 73 74 65 6d 20 73 70 61 63 65 20 74 68 61 74 20  stem space that 
26a0: 61 72 65 20 64 69 66 66 69 63 75 6c 74 20 74 6f  are difficult to
26b0: 20 74 65 73 74 20 6f 6e 20 61 20 72 65 61 6c 20   test on a real 
26c0: 73 79 73 74 65 6d 2e 0a 3c 2f 75 6c 3e 0a 0a 3c  system..</ul>..<
26d0: 70 3e 0a 54 68 65 72 65 20 61 72 65 20 6f 74 68  p>.There are oth
26e0: 65 72 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  er VFS implement
26f0: 61 74 69 6f 6e 73 20 62 6f 74 68 20 69 6e 20 74  ations both in t
2700: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 73  he core SQLite s
2710: 6f 75 72 63 65 20 63 6f 64 65 0a 6c 69 62 72 61  ource code.libra
2720: 72 79 20 61 6e 64 20 69 6e 20 61 76 61 69 6c 61  ry and in availa
2730: 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20  ble extensions. 
2740: 20 54 68 65 20 6c 69 73 74 20 61 62 6f 76 65 20   The list above 
2750: 69 73 20 6e 6f 74 20 6d 65 61 6e 74 20 74 6f 20  is not meant to 
2760: 62 65 0a 65 78 68 61 75 73 74 69 76 65 20 62 75  be.exhaustive bu
2770: 74 20 6d 65 72 65 6c 79 20 72 65 70 72 65 73 65  t merely represe
2780: 6e 74 61 74 69 76 65 20 6f 66 20 74 68 65 20 6b  ntative of the k
2790: 69 6e 64 73 20 6f 66 20 66 65 61 74 75 72 65 73  inds of features
27a0: 20 74 68 61 74 20 63 61 6e 0a 62 65 20 72 65 61   that can.be rea
27b0: 6c 69 7a 65 64 20 75 73 69 6e 67 20 74 68 65 20  lized using the 
27c0: 56 46 53 20 69 6e 74 65 72 66 61 63 65 2e 0a 3c  VFS interface..<
27d0: 2f 70 3e 0a 0a 3c 68 32 3e 33 2e 30 20 56 46 53  /p>..<h2>3.0 VFS
27e0: 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   Implementations
27f0: 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 41 20 6e 65 77  </h2>..<p>.A new
2800: 20 56 46 53 20 69 73 20 69 6d 70 6c 65 6d 65 6e   VFS is implemen
2810: 74 65 64 20 62 79 20 73 75 62 63 6c 61 73 73 69  ted by subclassi
2820: 6e 67 20 74 68 72 65 65 20 6f 62 6a 65 63 74 73  ng three objects
2830: 3a 0a 3c 2f 70 3e 0a 0a 3c 75 6c 3e 0a 3c 6c 69  :.</p>..<ul>.<li
2840: 3e 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a 3c  >[sqlite3_vfs].<
2850: 6c 69 3e 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  li>[sqlite3_io_m
2860: 65 74 68 6f 64 73 5d 0a 3c 6c 69 3e 5b 73 71 6c  ethods].<li>[sql
2870: 69 74 65 33 5f 66 69 6c 65 5d 0a 3c 2f 75 6c 3e  ite3_file].</ul>
2880: 0a 0a 3c 70 3e 0a 41 6e 20 5b 73 71 6c 69 74 65  ..<p>.An [sqlite
2890: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 64 65  3_vfs] object de
28a0: 66 69 6e 65 73 20 74 68 65 20 6e 61 6d 65 20 6f  fines the name o
28b0: 66 20 74 68 65 20 56 46 53 20 61 6e 64 20 74 68  f the VFS and th
28c0: 65 20 63 6f 72 65 0a 6d 65 74 68 6f 64 73 20 74  e core.methods t
28d0: 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
28e0: 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
28f0: 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
2900: 74 65 6d 2c 20 73 75 63 68 0a 61 73 20 63 68 65  tem, such.as che
2910: 63 6b 69 6e 67 20 66 6f 72 20 65 78 69 73 74 65  cking for existe
2920: 6e 63 65 20 6f 66 20 66 69 6c 65 73 2c 20 64 65  nce of files, de
2930: 6c 65 74 69 6e 67 20 66 69 6c 65 73 2c 20 63 72  leting files, cr
2940: 65 61 74 69 6e 67 20 66 69 6c 65 73 0a 61 6e 64  eating files.and
2950: 20 6f 70 65 6e 69 6e 67 20 61 6e 64 20 66 6f 72   opening and for
2960: 20 72 65 61 64 69 6e 67 20 61 6e 64 2f 6f 72 20   reading and/or 
2970: 77 72 69 74 69 6e 67 2c 20 63 6f 6e 76 65 72 74  writing, convert
2980: 69 6e 67 20 66 69 6c 65 6e 61 6d 65 73 0a 69 6e  ing filenames.in
2990: 74 6f 20 74 68 65 69 72 20 63 61 6e 6f 6e 69 63  to their canonic
29a0: 61 6c 20 66 6f 72 6d 2e 20 20 54 68 65 20 5b 73  al form.  The [s
29b0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
29c0: 63 74 20 61 6c 73 6f 20 63 6f 6e 74 61 69 6e 73  ct also contains
29d0: 0a 6d 65 74 68 6f 64 73 20 66 6f 72 20 6f 62 74  .methods for obt
29e0: 61 69 6e 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73  aining randomnes
29f0: 73 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  s from the opera
2a00: 74 69 6e 67 20 73 79 73 74 65 6d 2c 20 66 6f 72  ting system, for
2a10: 0a 73 75 73 70 65 6e 64 69 6e 67 20 61 20 70 72  .suspending a pr
2a20: 6f 63 65 73 73 20 28 73 6c 65 65 70 69 6e 67 29  ocess (sleeping)
2a30: 20 61 6e 64 20 66 6f 72 20 66 69 6e 64 69 6e 67   and for finding
2a40: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
2a50: 65 20 61 6e 64 0a 74 69 6d 65 2e 0a 3c 2f 70 3e  e and.time..</p>
2a60: 0a 0a 3c 70 3e 0a 54 68 65 20 5b 73 71 6c 69 74  ..<p>.The [sqlit
2a70: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
2a80: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
2a90: 65 6e 20 66 69 6c 65 2e 0a 54 68 65 20 78 4f 70  en file..The xOp
2aa0: 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  en method of [sq
2ab0: 6c 69 74 65 33 5f 76 66 73 5d 20 63 6f 6e 73 74  lite3_vfs] const
2ac0: 72 75 63 74 73 20 61 6e 20 5b 73 71 6c 69 74 65  ructs an [sqlite
2ad0: 33 5f 66 69 6c 65 5d 0a 6f 62 6a 65 63 74 20 77  3_file].object w
2ae0: 68 65 6e 20 74 68 65 20 66 69 6c 65 20 69 73 20  hen the file is 
2af0: 6f 70 65 6e 65 64 2e 20 20 54 68 65 20 5b 73 71  opened.  The [sq
2b00: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6b 65 65 70  lite3_file] keep
2b10: 73 20 74 72 61 63 6b 0a 6f 66 20 74 68 65 20 73  s track.of the s
2b20: 74 61 74 65 20 6f 66 20 74 68 65 20 66 69 6c 65  tate of the file
2b30: 20 77 68 69 6c 65 20 69 74 20 69 73 20 6f 70 65   while it is ope
2b40: 6e 65 64 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54  ned..</p>..<p>.T
2b50: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
2b60: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 68  ethods] object h
2b70: 6f 6c 64 73 20 74 68 65 20 6d 65 74 68 6f 64 73  olds the methods
2b80: 20 75 73 65 64 20 74 6f 20 69 6e 74 65 72 61 63   used to interac
2b90: 74 0a 77 69 74 68 20 61 6e 20 6f 70 65 6e 20 66  t.with an open f
2ba0: 69 6c 65 2e 20 20 45 61 63 68 20 5b 73 71 6c 69  ile.  Each [sqli
2bb0: 74 65 33 5f 66 69 6c 65 5d 20 63 6f 6e 74 61 69  te3_file] contai
2bc0: 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2bd0: 0a 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .an [sqlite3_io_
2be0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
2bf0: 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69  that is appropri
2c00: 61 74 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ate for the file
2c10: 20 69 74 0a 72 65 70 72 65 73 65 6e 74 73 2e 20   it.represents. 
2c20: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   The [sqlite3_io
2c30: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
2c40: 20 63 6f 6e 74 61 69 6e 73 20 6d 65 74 68 6f 64   contains method
2c50: 73 20 74 6f 20 64 6f 0a 74 68 69 6e 67 73 20 73  s to do.things s
2c60: 75 63 68 20 61 73 20 72 65 61 64 20 61 6e 64 20  uch as read and 
2c70: 77 72 69 74 65 20 66 72 6f 6d 20 74 68 65 20 66  write from the f
2c80: 69 6c 65 2c 20 74 6f 20 74 72 75 6e 63 61 74 65  ile, to truncate
2c90: 20 74 68 65 20 66 69 6c 65 2c 0a 74 6f 20 66 6c   the file,.to fl
2ca0: 75 73 68 20 61 6e 79 20 63 68 61 6e 67 65 73 20  ush any changes 
2cb0: 74 6f 20 70 65 72 73 69 73 74 65 6e 74 20 73 74  to persistent st
2cc0: 6f 72 61 67 65 2c 20 74 6f 20 66 69 6e 64 20 74  orage, to find t
2cd0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 66  he size of the.f
2ce0: 69 6c 65 2c 20 74 6f 20 6c 6f 63 6b 20 61 6e 64  ile, to lock and
2cf0: 20 75 6e 6c 6f 63 6b 20 74 68 65 20 66 69 6c 65   unlock the file
2d00: 2c 20 61 6e 64 20 74 6f 20 63 6c 6f 73 65 20 66  , and to close f
2d10: 69 6c 65 20 61 6e 64 20 64 65 73 74 72 6f 79 0a  ile and destroy.
2d20: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
2d30: 65 5d 20 6f 62 6a 65 63 74 2e 0a 3c 2f 70 3e 0a  e] object..</p>.
2d40: 0a 3c 70 3e 0a 57 72 69 74 69 6e 67 20 74 68 65  .<p>.Writing the
2d50: 20 63 6f 64 65 20 66 6f 72 20 61 20 6e 65 77 20   code for a new 
2d60: 56 46 53 20 69 6e 76 6f 6c 76 65 73 20 63 6f 6e  VFS involves con
2d70: 73 74 72 75 63 74 69 6e 67 20 61 20 73 75 62 63  structing a subc
2d80: 6c 61 73 73 20 66 6f 72 0a 74 68 65 20 5b 73 71  lass for.the [sq
2d90: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
2da0: 74 20 61 6e 64 20 74 68 65 6e 20 72 65 67 69 73  t and then regis
2db0: 74 65 72 69 6e 67 20 74 68 61 74 20 56 46 53 20  tering that VFS 
2dc0: 6f 62 6a 65 63 74 20 75 73 69 6e 67 0a 61 20 63  object using.a c
2dd0: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2de0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 2e  vfs_register()].
2df0: 20 20 54 68 65 20 56 46 53 20 69 6d 70 6c 65 6d    The VFS implem
2e00: 65 6e 74 61 74 69 6f 6e 20 61 6c 73 6f 0a 70 72  entation also.pr
2e10: 6f 76 69 64 65 73 20 73 75 62 63 6c 61 73 73 65  ovides subclasse
2e20: 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  s for [sqlite3_f
2e30: 69 6c 65 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  ile] and [sqlite
2e40: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 62 75  3_io_methods] bu
2e50: 74 0a 74 68 6f 73 65 20 6f 62 6a 65 63 74 73 20  t.those objects 
2e60: 61 72 65 20 6e 6f 74 20 72 65 67 69 73 74 65 72  are not register
2e70: 65 64 20 64 69 72 65 63 74 6c 79 20 77 69 74 68  ed directly with
2e80: 20 53 51 4c 69 74 65 2e 20 20 49 6e 73 74 65 61   SQLite.  Instea
2e90: 64 2c 20 74 68 65 0a 5b 73 71 6c 69 74 65 33 5f  d, the.[sqlite3_
2ea0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  file] object is 
2eb0: 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68  returned from th
2ec0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f  e xOpen method o
2ed0: 66 0a 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  f.[sqlite3_vfs] 
2ee0: 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
2ef0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 70 6f  _file] object po
2f00: 69 6e 74 73 20 74 6f 20 61 6e 20 69 6e 73 74 61  ints to an insta
2f10: 6e 63 65 0a 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce.of the [sqli
2f20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
2f30: 6f 62 6a 65 63 74 2e 0a 3c 2f 70 3e 0a 0a 3c 68  object..</p>..<h
2f40: 32 3e 54 6f 20 42 65 20 43 6f 6e 74 69 6e 75 65  2>To Be Continue
2f50: 64 2e 2e 2e 3c 2f 68 32 3e 0a                    d...</h2>.