Documentation Source Text

Hex Artifact Content
Login

Artifact ac16fec6109df26515b4af209fa224fbf05848b3:


0000: 3c 74 69 74 6c 65 3e 4d 65 6d 6f 72 79 2d 4d 61  <title>Memory-Ma
0010: 70 70 65 64 20 49 2f 4f 3c 2f 74 69 74 6c 65 3e  pped I/O</title>
0020: 0a 3c 74 63 6c 3e 68 64 5f 6b 65 79 77 6f 72 64  .<tcl>hd_keyword
0030: 73 20 7b 6d 6d 61 70 7d 20 7b 6d 65 6d 6f 72 79  s {mmap} {memory
0040: 2d 6d 61 70 70 65 64 20 49 2f 4f 7d 3c 2f 74 63  -mapped I/O}</tc
0050: 6c 3e 0a 0a 3c 68 31 20 61 6c 69 67 6e 3d 22 63  l>..<h1 align="c
0060: 65 6e 74 65 72 22 3e 4d 65 6d 6f 72 79 2d 4d 61  enter">Memory-Ma
0070: 70 70 65 64 20 49 2f 4f 3c 2f 68 31 3e 0a 0a 3c  pped I/O</h1>..<
0080: 70 3e 54 68 65 20 64 65 66 61 75 6c 74 20 6d 65  p>The default me
0090: 63 68 61 6e 69 73 6d 20 62 79 20 77 68 69 63 68  chanism by which
00a0: 20 53 51 4c 69 74 65 20 61 63 63 65 73 73 65 73   SQLite accesses
00b0: 20 61 6e 64 20 75 70 64 61 74 65 73 20 64 61 74   and updates dat
00c0: 61 62 61 73 65 20 64 69 73 6b 0a 66 69 6c 65 73  abase disk.files
00d0: 20 69 73 20 74 68 65 20 78 52 65 61 64 28 29 20   is the xRead() 
00e0: 61 6e 64 20 78 57 72 69 74 65 28 29 20 6d 65 74  and xWrite() met
00f0: 68 6f 64 73 20 6f 66 20 74 68 65 0a 5b 73 71 6c  hods of the.[sql
0100: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
0110: 20 56 46 53 20 6f 62 6a 65 63 74 2e 20 20 54 68   VFS object.  Th
0120: 65 73 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  ese methods are 
0130: 74 79 70 69 63 61 6c 6c 79 20 69 6d 70 6c 65 6d  typically implem
0140: 65 6e 74 65 64 20 61 73 0a 22 72 65 61 64 28 29  ented as."read()
0150: 22 20 61 6e 64 20 22 77 72 69 74 65 28 29 22 20  " and "write()" 
0160: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 68 69  system calls whi
0170: 63 68 20 63 61 75 73 65 20 74 68 65 20 6f 70 65  ch cause the ope
0180: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 0a 74 6f  rating system.to
0190: 20 63 6f 70 79 20 64 69 73 6b 20 63 6f 6e 74 65   copy disk conte
01a0: 6e 74 20 62 65 74 77 65 65 6e 20 74 68 65 20 6b  nt between the k
01b0: 65 72 6e 65 6c 20 62 75 66 66 65 72 20 63 61 63  ernel buffer cac
01c0: 68 65 20 61 6e 64 20 75 73 65 72 20 73 70 61 63  he and user spac
01d0: 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e 42 65 67 69 6e  e.</p>..<p>Begin
01e0: 6e 69 6e 67 20 77 69 74 68 20 5b 76 65 72 73 69  ning with [versi
01f0: 6f 6e 20 33 2e 37 2e 31 37 5d 20 28 5b 64 61 74  on 3.7.17] ([dat
0200: 65 6f 66 3a 33 2e 37 2e 31 37 5d 29 2c 20 53 51  eof:3.7.17]), SQ
0210: 4c 69 74 65 20 68 61 73 20 74 68 65 20 6f 70 74  Lite has the opt
0220: 69 6f 6e 20 6f 66 20 0a 61 63 63 65 73 73 69 6e  ion of .accessin
0230: 67 20 64 69 73 6b 20 63 6f 6e 74 65 6e 74 20 64  g disk content d
0240: 69 72 65 63 74 6c 79 20 75 73 69 6e 67 20 6d 65  irectly using me
0250: 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 20  mory-mapped I/O 
0260: 61 6e 64 20 74 68 65 20 6e 65 77 0a 78 46 65 74  and the new.xFet
0270: 63 68 28 29 20 61 6e 64 20 78 55 6e 66 65 74 63  ch() and xUnfetc
0280: 68 28 29 20 6d 65 74 68 6f 64 73 20 6f 6e 20 5b  h() methods on [
0290: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
02a0: 64 73 5d 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65  ds].</p>..<p>The
02b0: 72 65 20 61 72 65 20 61 64 76 61 6e 74 61 67 65  re are advantage
02c0: 73 20 61 6e 64 20 64 69 73 61 64 76 61 6e 74 61  s and disadvanta
02d0: 67 65 73 20 74 6f 20 75 73 69 6e 67 20 6d 65 6d  ges to using mem
02e0: 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a  ory-mapped I/O..
02f0: 41 64 76 61 6e 74 61 67 65 73 20 69 6e 63 6c 75  Advantages inclu
0300: 64 65 3a 3c 2f 70 3e 0a 0a 3c 6f 6c 3e 0a 3c 6c  de:</p>..<ol>.<l
0310: 69 3e 3c 70 3e 4d 61 6e 79 20 6f 70 65 72 61 74  i><p>Many operat
0320: 69 6f 6e 73 2c 20 65 73 70 65 63 69 61 6c 6c 79  ions, especially
0330: 20 49 2f 4f 20 69 6e 74 65 6e 73 69 76 65 20 6f   I/O intensive o
0340: 70 65 72 61 74 69 6f 6e 73 2c 20 63 61 6e 20 62  perations, can b
0350: 65 20 6d 75 63 68 0a 20 20 20 20 66 61 73 74 65  e much.    faste
0360: 72 20 73 69 6e 63 65 20 63 6f 6e 74 65 6e 74 20  r since content 
0370: 64 6f 65 73 20 6e 65 65 64 20 74 6f 20 62 65 20  does need to be 
0380: 63 6f 70 69 65 64 20 62 65 74 77 65 65 6e 20 6b  copied between k
0390: 65 72 6e 65 6c 20 73 70 61 63 65 0a 20 20 20 20  ernel space.    
03a0: 61 6e 64 20 75 73 65 72 20 73 70 61 63 65 2e 20  and user space. 
03b0: 20 49 6e 20 73 6f 6d 65 20 63 61 73 65 73 2c 20   In some cases, 
03c0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 63 61 6e 20  performance can 
03d0: 6e 65 61 72 6c 79 20 64 6f 75 62 6c 65 2e 3c 2f  nearly double.</
03e0: 70 3e 0a 0a 3c 6c 69 3e 3c 70 3e 54 68 65 20 53  p>..<li><p>The S
03f0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 6d 61  QLite library ma
0400: 79 20 6e 65 65 64 20 6c 65 73 73 20 52 41 4d 20  y need less RAM 
0410: 73 69 6e 63 65 20 69 74 20 73 68 61 72 65 73 20  since it shares 
0420: 70 61 67 65 73 20 77 69 74 68 0a 20 20 20 20 74  pages with.    t
0430: 68 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  he operating-sys
0440: 74 65 6d 20 70 61 67 65 20 63 61 63 68 65 20 61  tem page cache a
0450: 6e 64 20 64 6f 65 73 20 6e 6f 74 20 61 6c 77 61  nd does not alwa
0460: 79 73 20 6e 65 65 64 20 69 74 73 20 6f 77 6e 20  ys need its own 
0470: 63 6f 70 79 20 6f 66 0a 20 20 20 20 77 6f 72 6b  copy of.    work
0480: 69 6e 67 20 70 61 67 65 73 2e 3c 2f 70 3e 0a 3c  ing pages.</p>.<
0490: 2f 6f 6c 3e 0a 0a 3c 70 3e 42 75 74 20 74 68 65  /ol>..<p>But the
04a0: 72 65 20 61 72 65 20 61 6c 73 6f 20 64 69 73 61  re are also disa
04b0: 64 76 61 6e 74 61 67 65 73 3a 3c 2f 70 3e 0a 0a  dvantages:</p>..
04c0: 3c 6f 6c 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 73 74  <ol>.<li><p>A st
04d0: 72 61 79 20 70 6f 69 6e 74 65 72 20 6f 72 20 62  ray pointer or b
04e0: 75 66 66 65 72 20 6f 76 65 72 66 6c 6f 77 20 69  uffer overflow i
04f0: 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  n the applicatio
0500: 6e 20 70 72 6f 67 72 61 6d 0a 20 20 20 20 6d 69  n program.    mi
0510: 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 63  ght change the c
0520: 6f 6e 74 65 6e 74 20 6f 66 20 6d 61 70 70 65 64  ontent of mapped
0530: 20 6d 65 6d 6f 72 79 2c 20 70 6f 74 65 6e 74 69   memory, potenti
0540: 61 6c 6c 79 20 63 6f 72 72 75 70 74 69 6e 67 20  ally corrupting 
0550: 74 68 65 0a 20 20 20 20 64 61 74 61 62 61 73 65  the.    database
0560: 20 66 69 6c 65 2e 20 20 42 75 67 73 20 69 6e 20   file.  Bugs in 
0570: 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 67  application prog
0580: 72 61 6d 20 74 68 61 74 20 6f 76 65 72 77 72 69  ram that overwri
0590: 74 65 20 6d 65 6d 6f 72 79 0a 20 20 20 20 61 73  te memory.    as
05a0: 73 69 67 6e 65 64 20 74 6f 20 74 68 65 20 53 51  signed to the SQ
05b0: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 63 6f 75  Lite library cou
05c0: 6c 64 2c 20 69 6e 20 74 68 65 6f 72 79 2c 20 61  ld, in theory, a
05d0: 6c 73 6f 20 63 61 75 73 65 20 63 6f 72 72 75 70  lso cause corrup
05e0: 74 69 6f 6e 0a 20 20 20 20 69 6e 20 72 65 61 64  tion.    in read
05f0: 2f 77 72 69 74 65 20 6d 6f 64 65 2c 20 62 75 74  /write mode, but
0600: 20 74 68 61 74 20 77 6f 75 6c 64 20 72 65 71 75   that would requ
0610: 69 72 65 20 74 68 61 74 20 74 68 65 20 6f 76 65  ire that the ove
0620: 72 77 72 69 74 65 0a 20 20 20 20 62 65 20 66 6f  rwrite.    be fo
0630: 6c 6c 6f 77 65 64 20 62 79 20 61 20 63 61 6c 6c  llowed by a call
0640: 20 74 6f 20 78 57 72 69 74 65 28 29 20 61 6e 64   to xWrite() and
0650: 20 69 6e 20 70 72 61 63 74 69 63 65 20 74 68 65   in practice the
0660: 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
0670: 6f 6e 0a 20 20 20 20 75 73 75 61 6c 6c 79 20 65  on.    usually e
0680: 72 72 6f 72 73 20 6f 75 74 20 6f 72 20 63 72 61  rrors out or cra
0690: 73 68 65 73 20 62 65 66 6f 72 65 20 74 68 61 74  shes before that
06a0: 20 70 6f 69 6e 74 2e 20 20 57 69 74 68 20 6d 65   point.  With me
06b0: 6d 6f 72 79 2d 6d 61 70 70 65 64 0a 20 20 20 20  mory-mapped.    
06c0: 49 2f 4f 2c 20 74 68 65 20 64 61 74 61 62 61 73  I/O, the databas
06d0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6f 63 63  e corruption occ
06e0: 75 72 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  urs immediately 
06f0: 61 6e 64 20 69 73 20 74 68 75 73 20 6d 6f 72 65  and is thus more
0700: 20 6f 66 20 61 0a 20 20 20 20 72 69 73 6b 2e 3c   of a.    risk.<
0710: 2f 70 3e 0a 0a 3c 6c 69 3e 3c 70 3e 41 6e 20 49  /p>..<li><p>An I
0720: 2f 4f 20 65 72 72 6f 72 20 6f 6e 20 61 20 6d 65  /O error on a me
0730: 6d 6f 72 79 2d 6d 61 70 70 65 64 20 66 69 6c 65  mory-mapped file
0740: 20 63 61 6e 6e 6f 74 20 62 65 20 63 61 75 67 68   cannot be caugh
0750: 74 20 61 6e 64 20 64 65 61 6c 74 20 77 69 74 68  t and dealt with
0760: 20 62 79 0a 20 20 20 20 53 51 4c 69 74 65 2e 20   by.    SQLite. 
0770: 20 49 6e 73 74 65 61 64 2c 20 74 68 65 20 49 2f   Instead, the I/
0780: 4f 20 65 72 72 6f 72 20 63 61 75 73 65 73 20 61  O error causes a
0790: 20 73 69 67 6e 61 6c 20 77 68 69 63 68 2c 20 69   signal which, i
07a0: 66 20 6e 6f 74 20 63 61 75 67 68 74 0a 20 20 20  f not caught.   
07b0: 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
07c0: 69 6f 6e 2c 20 72 65 73 75 6c 74 73 20 69 6e 20  ion, results in 
07d0: 61 20 70 72 6f 67 72 61 6d 20 63 72 61 73 68 2e  a program crash.
07e0: 3c 2f 70 3e 0a 0a 3c 6c 69 3e 3c 70 3e 54 68 65  </p>..<li><p>The
07f0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
0800: 6d 20 6d 75 73 74 20 68 61 76 65 20 61 20 75 6e  m must have a un
0810: 69 66 69 65 64 20 62 75 66 66 65 72 20 63 61 63  ified buffer cac
0820: 68 65 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 0a  he in order for.
0830: 20 20 20 20 74 68 65 20 6d 65 6d 6f 72 79 2d 6d      the memory-m
0840: 61 70 70 65 64 20 49 2f 4f 20 65 78 74 65 6e 73  apped I/O extens
0850: 69 6f 6e 20 74 6f 20 77 6f 72 6b 20 63 6f 72 72  ion to work corr
0860: 65 63 74 6c 79 2c 20 65 73 70 65 63 69 61 6c 6c  ectly, especiall
0870: 79 20 69 6e 0a 20 20 20 20 73 69 74 75 61 74 69  y in.    situati
0880: 6f 6e 73 20 77 68 65 72 65 20 74 77 6f 20 70 72  ons where two pr
0890: 6f 63 65 73 73 65 73 20 61 72 65 20 61 63 63 65  ocesses are acce
08a0: 73 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 64  ssing the same d
08b0: 61 74 61 62 61 73 65 0a 20 20 20 20 66 69 6c 65  atabase.    file
08c0: 20 61 6e 64 20 6f 6e 65 20 70 72 6f 63 65 73 73   and one process
08d0: 20 69 73 20 75 73 69 6e 67 20 6d 65 6d 6f 72 79   is using memory
08e0: 2d 6d 61 70 70 65 64 20 49 2f 4f 20 77 68 69 6c  -mapped I/O whil
08f0: 65 20 74 68 65 20 6f 74 68 65 72 0a 20 20 20 20  e the other.    
0900: 69 73 20 6e 6f 74 2e 20 20 4e 6f 74 20 61 6c 6c  is not.  Not all
0910: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
0920: 6d 73 20 68 61 76 65 20 61 20 75 6e 69 66 69 65  ms have a unifie
0930: 64 20 62 75 66 66 65 72 20 63 61 63 68 65 2e 0a  d buffer cache..
0940: 20 20 20 20 49 6e 20 73 6f 6d 65 20 6f 70 65 72      In some oper
0950: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 74 68  ating systems th
0960: 61 74 20 63 6c 61 69 6d 20 74 6f 20 68 61 76 65  at claim to have
0970: 20 61 20 75 6e 69 66 69 65 64 20 62 75 66 66 65   a unified buffe
0980: 72 20 63 61 63 68 65 2c 0a 20 20 20 20 74 68 65  r cache,.    the
0990: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
09a0: 69 73 20 62 75 67 67 79 20 61 6e 64 20 63 61 6e  is buggy and can
09b0: 20 6c 65 61 64 20 74 6f 20 63 6f 72 72 75 70 74   lead to corrupt
09c0: 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 70 3e 0a   databases.</p>.
09d0: 0a 3c 6c 69 3e 3c 70 3e 50 65 72 66 6f 72 6d 61  .<li><p>Performa
09e0: 6e 63 65 20 64 6f 65 73 20 6e 6f 74 20 61 6c 77  nce does not alw
09f0: 61 79 73 20 69 6e 63 72 65 61 73 65 20 77 69 74  ays increase wit
0a00: 68 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  h memory-mapped 
0a10: 49 2f 4f 2e 20 20 49 6e 20 66 61 63 74 2c 0a 20  I/O.  In fact,. 
0a20: 20 20 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c     it is possibl
0a30: 65 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 74  e to construct t
0a40: 65 73 74 20 63 61 73 65 73 20 77 68 65 72 65 20  est cases where 
0a50: 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 72  performance is r
0a60: 65 64 75 63 65 64 0a 20 20 20 20 62 79 20 74 68  educed.    by th
0a70: 65 20 75 73 65 20 6f 66 20 6d 65 6d 6f 72 79 2d  e use of memory-
0a80: 6d 61 70 70 65 64 20 49 2f 4f 2c 20 74 68 6f 75  mapped I/O, thou
0a90: 67 68 20 74 68 69 73 20 69 73 20 68 61 72 64 20  gh this is hard 
0aa0: 74 6f 20 64 6f 2e 3c 2f 70 3e 0a 0a 3c 6c 69 3e  to do.</p>..<li>
0ab0: 3c 70 3e 57 69 6e 64 6f 77 73 20 69 73 20 75 6e  <p>Windows is un
0ac0: 61 62 6c 65 20 74 6f 20 74 72 75 6e 63 61 74 65  able to truncate
0ad0: 20 61 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64   a memory-mapped
0ae0: 20 66 69 6c 65 2e 20 20 48 65 6e 63 65 2c 20 6f   file.  Hence, o
0af0: 6e 20 57 69 6e 64 6f 77 73 2c 0a 20 20 20 20 69  n Windows,.    i
0b00: 66 20 61 6e 20 6f 70 65 72 61 74 69 6f 6e 20 73  f an operation s
0b10: 75 63 68 20 61 73 20 5b 56 41 43 55 55 4d 5d 20  uch as [VACUUM] 
0b20: 6f 72 20 5b 61 75 74 6f 5f 76 61 63 75 75 6d 5d  or [auto_vacuum]
0b30: 20 74 72 69 65 73 20 74 6f 20 72 65 64 75 63 65   tries to reduce
0b40: 20 74 68 65 0a 20 20 20 20 73 69 7a 65 20 6f 66   the.    size of
0b50: 20 61 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64   a memory-mapped
0b60: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
0b70: 74 68 65 20 73 69 7a 65 20 72 65 64 75 63 74 69  the size reducti
0b80: 6f 6e 20 61 74 74 65 6d 70 74 20 77 69 6c 6c 0a  on attempt will.
0b90: 20 20 20 20 73 69 6c 65 6e 74 6c 79 20 66 61 69      silently fai
0ba0: 6c 2c 20 6c 65 61 76 69 6e 67 20 75 6e 75 73 65  l, leaving unuse
0bb0: 64 20 73 70 61 63 65 20 61 74 20 74 68 65 20 65  d space at the e
0bc0: 6e 64 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nd of the databa
0bd0: 73 65 20 66 69 6c 65 2e 0a 20 20 20 20 4e 6f 20  se file..    No 
0be0: 64 61 74 61 20 69 73 20 6c 6f 73 74 20 64 75 65  data is lost due
0bf0: 20 74 6f 20 74 68 69 73 20 70 72 6f 62 6c 65 6d   to this problem
0c00: 2c 20 61 6e 64 20 74 68 65 20 75 6e 75 73 65 64  , and the unused
0c10: 20 73 70 61 63 65 20 77 69 6c 6c 20 62 65 0a 20   space will be. 
0c20: 20 20 20 72 65 75 73 65 64 20 61 67 61 69 6e 20     reused again 
0c30: 74 68 65 20 6e 65 78 74 20 74 69 6d 65 20 74 68  the next time th
0c40: 65 20 64 61 74 61 62 61 73 65 20 67 72 6f 77 73  e database grows
0c50: 2e 20 20 48 6f 77 65 76 65 72 20 69 66 20 61 20  .  However if a 
0c60: 76 65 72 73 69 6f 6e 20 0a 20 20 20 20 6f 66 20  version .    of 
0c70: 53 51 4c 69 74 65 20 70 72 69 6f 72 20 74 6f 20  SQLite prior to 
0c80: 33 2e 37 2e 30 20 72 75 6e 73 20 5b 50 52 41 47  3.7.0 runs [PRAG
0c90: 4d 41 20 69 6e 74 65 67 72 69 74 79 5f 63 68 65  MA integrity_che
0ca0: 63 6b 5d 20 6f 6e 20 73 75 63 68 20 61 20 0a 20  ck] on such a . 
0cb0: 20 20 20 64 61 74 61 62 61 73 65 2c 20 69 74 20     database, it 
0cc0: 77 69 6c 6c 20 28 69 6e 63 6f 72 72 65 63 74 6c  will (incorrectl
0cd0: 79 29 20 72 65 70 6f 72 74 20 64 61 74 61 62 61  y) report databa
0ce0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 64 75  se corruption du
0cf0: 65 20 74 6f 20 0a 20 20 20 20 74 68 65 20 75 6e  e to .    the un
0d00: 75 73 65 64 20 73 70 61 63 65 20 61 74 20 74 68  used space at th
0d10: 65 20 65 6e 64 2e 20 20 4f 72 20 69 66 20 61 20  e end.  Or if a 
0d20: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
0d30: 65 20 70 72 69 6f 72 20 74 6f 20 33 2e 37 2e 30  e prior to 3.7.0
0d40: 0a 20 20 20 20 77 72 69 74 65 73 20 74 6f 20 74  .    writes to t
0d50: 68 65 20 64 61 74 61 62 61 73 65 20 77 68 69 6c  he database whil
0d60: 65 20 69 74 20 73 74 69 6c 6c 20 68 61 73 20 75  e it still has u
0d70: 6e 75 73 65 64 20 73 70 61 63 65 20 61 74 20 74  nused space at t
0d80: 68 65 20 65 6e 64 2c 20 69 74 0a 20 20 20 20 6d  he end, it.    m
0d90: 61 79 20 6d 61 6b 65 20 74 68 61 74 20 75 6e 75  ay make that unu
0da0: 73 65 64 20 73 70 61 63 65 20 69 6e 61 63 63 65  sed space inacce
0db0: 73 73 69 62 6c 65 20 61 6e 64 20 75 6e 61 76 61  ssible and unava
0dc0: 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65  ilable for reuse
0dd0: 20 75 6e 74 69 6c 0a 20 20 20 20 61 66 74 65 72   until.    after
0de0: 20 74 68 65 20 6e 65 78 74 20 5b 56 41 43 55 55   the next [VACUU
0df0: 4d 5d 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 42 65  M]..</ol>..<p>Be
0e00: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 6f 74  cause of the pot
0e10: 65 6e 74 69 61 6c 20 64 69 73 61 64 76 61 6e 74  ential disadvant
0e20: 61 67 65 73 2c 20 6d 65 6d 6f 72 79 2d 6d 61 70  ages, memory-map
0e30: 70 65 64 20 49 2f 4f 20 69 73 20 74 75 72 6e 65  ped I/O is turne
0e40: 64 0a 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74  d.off by default
0e50: 2e 20 20 54 6f 20 61 63 74 69 76 61 74 65 20 6d  .  To activate m
0e60: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
0e70: 2c 20 75 73 65 20 74 68 65 20 5b 6d 6d 61 70 5f  , use the [mmap_
0e80: 73 69 7a 65 20 70 72 61 67 6d 61 5d 0a 61 6e 64  size pragma].and
0e90: 20 73 65 74 20 74 68 65 20 6d 6d 61 70 5f 73 69   set the mmap_si
0ea0: 7a 65 20 74 6f 20 73 6f 6d 65 20 6c 61 72 67 65  ze to some large
0eb0: 20 6e 75 6d 62 65 72 2c 20 75 73 75 61 6c 6c 79   number, usually
0ec0: 20 32 35 36 4d 42 20 6f 72 20 6c 61 72 67 65 72   256MB or larger
0ed0: 2c 20 64 65 70 65 6e 64 69 6e 67 0a 6f 6e 20 68  , depending.on h
0ee0: 6f 77 20 6d 75 63 68 20 61 64 64 72 65 73 73 20  ow much address 
0ef0: 73 70 61 63 65 20 79 6f 75 72 20 61 70 70 6c 69  space your appli
0f00: 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 61 72 65  cation can spare
0f10: 2e 20 20 54 68 65 20 72 65 73 74 20 69 73 0a 61  .  The rest is.a
0f20: 75 74 6f 6d 61 74 69 63 2e 20 20 54 68 65 20 5b  utomatic.  The [
0f30: 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
0f40: 5d 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  ] statement will
0f50: 20 62 65 20 61 20 73 69 6c 65 6e 74 20 6e 6f 2d   be a silent no-
0f60: 6f 70 20 6f 6e 0a 73 79 73 74 65 6d 73 20 74 68  op on.systems th
0f70: 61 74 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72  at do not suppor
0f80: 74 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  t memory-mapped 
0f90: 49 2f 4f 2e 3c 2f 70 3e 0a 0a 3c 68 32 3e 48 6f  I/O.</p>..<h2>Ho
0fa0: 77 20 4d 65 6d 6f 72 79 2d 4d 61 70 70 65 64 20  w Memory-Mapped 
0fb0: 49 2f 4f 20 57 6f 72 6b 73 3c 2f 68 32 3e 0a 0a  I/O Works</h2>..
0fc0: 3c 70 3e 54 6f 20 72 65 61 64 20 61 20 70 61 67  <p>To read a pag
0fd0: 65 20 6f 66 20 64 61 74 61 62 61 73 65 20 63 6f  e of database co
0fe0: 6e 74 65 6e 74 20 75 73 69 6e 67 20 74 68 65 20  ntent using the 
0ff0: 6c 65 67 61 63 79 20 78 52 65 61 64 28 29 20 6d  legacy xRead() m
1000: 65 74 68 6f 64 2c 0a 53 51 4c 69 74 65 20 66 69  ethod,.SQLite fi
1010: 72 73 74 20 61 6c 6c 6f 63 61 74 65 73 20 61 20  rst allocates a 
1020: 70 61 67 65 2d 73 69 7a 65 20 63 68 75 6e 6b 20  page-size chunk 
1030: 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
1040: 68 65 6e 20 69 6e 76 6f 6b 65 73 0a 74 68 65 20  hen invokes.the 
1050: 78 52 65 61 64 28 29 20 6d 65 74 68 6f 64 20 77  xRead() method w
1060: 68 69 63 68 20 63 61 75 73 65 73 20 74 68 65 20  hich causes the 
1070: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 6f  database page co
1080: 6e 74 65 6e 74 20 74 6f 20 62 65 20 63 6f 70 69  ntent to be copi
1090: 65 64 0a 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c  ed.into the newl
10a0: 79 20 61 6c 6c 6f 63 61 74 65 64 20 68 65 61 70  y allocated heap
10b0: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 69 73 20 69   memory.  This i
10c0: 6e 76 6f 6c 76 65 73 20 28 61 74 20 61 20 6d 69  nvolves (at a mi
10d0: 6e 69 6d 75 6d 29 0a 61 20 63 6f 70 79 20 6f 66  nimum).a copy of
10e0: 20 74 68 65 20 65 6e 74 69 72 65 20 70 61 67 65   the entire page
10f0: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 42 75 74 20 69 66  .</p>..<p>But if
1100: 20 53 51 4c 69 74 65 20 77 61 6e 74 73 20 74 6f   SQLite wants to
1110: 20 61 63 63 65 73 73 20 61 20 70 61 67 65 20 6f   access a page o
1120: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
1130: 69 6c 65 20 61 6e 64 0a 6d 65 6d 6f 72 79 20 6d  ile and.memory m
1140: 61 70 70 65 64 20 49 2f 4f 20 69 73 20 65 6e 61  apped I/O is ena
1150: 62 6c 65 64 2c 20 69 74 20 66 69 72 73 74 20 63  bled, it first c
1160: 61 6c 6c 73 20 74 68 65 20 78 46 65 74 63 68 28  alls the xFetch(
1170: 29 20 6d 65 74 68 6f 64 2e 0a 54 68 65 20 78 46  ) method..The xF
1180: 65 74 63 68 28 29 20 6d 65 74 68 6f 64 20 61 73  etch() method as
1190: 6b 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  ks the operating
11a0: 20 73 79 73 74 65 6d 20 74 6f 20 72 65 74 75 72   system to retur
11b0: 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 74  n a pointer to.t
11c0: 68 65 20 72 65 71 75 65 73 74 65 64 20 70 61 67  he requested pag
11d0: 65 2c 20 69 66 20 70 6f 73 73 69 62 6c 65 2e 20  e, if possible. 
11e0: 20 49 66 20 74 68 65 20 72 65 71 75 65 73 74 65   If the requeste
11f0: 64 20 70 61 67 65 20 68 61 73 20 62 65 65 6e 20  d page has been 
1200: 6f 72 0a 63 61 6e 20 62 65 20 6d 61 70 70 65 64  or.can be mapped
1210: 20 69 6e 74 6f 20 74 68 65 20 61 70 70 6c 69 63   into the applic
1220: 61 74 69 6f 6e 20 61 64 64 72 65 73 73 20 73 70  ation address sp
1230: 61 63 65 2c 20 74 68 65 6e 20 78 46 65 74 63 68  ace, then xFetch
1240: 20 72 65 74 75 72 6e 73 0a 61 20 70 6f 69 6e 74   returns.a point
1250: 65 72 20 74 6f 20 74 68 61 74 20 70 61 67 65 20  er to that page 
1260: 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
1270: 65 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67  e without having
1280: 20 74 6f 20 63 6f 70 79 20 61 6e 79 74 68 69 6e   to copy anythin
1290: 67 2e 0a 53 6b 69 70 70 69 6e 67 20 74 68 65 20  g..Skipping the 
12a0: 63 6f 70 79 20 73 74 65 70 20 69 73 20 77 68 61  copy step is wha
12b0: 74 20 6d 61 6b 65 73 20 6d 65 6d 6f 72 79 20 6d  t makes memory m
12c0: 61 70 70 65 64 20 49 2f 4f 20 66 61 73 74 65 72  apped I/O faster
12d0: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 53 51 4c 69 74 65  .</p>..<p>SQLite
12e0: 20 64 6f 65 73 20 6e 6f 74 20 61 73 73 75 6d 65   does not assume
12f0: 20 74 68 61 74 20 74 68 65 20 78 46 65 74 63 68   that the xFetch
1300: 28 29 20 6d 65 74 68 6f 64 20 77 69 6c 6c 20 77  () method will w
1310: 6f 72 6b 2e 20 20 49 66 0a 61 20 63 61 6c 6c 20  ork.  If.a call 
1320: 74 6f 20 78 46 65 74 63 68 28 29 20 72 65 74 75  to xFetch() retu
1330: 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1340: 65 72 20 28 69 6e 64 69 63 61 74 69 6e 67 20 74  er (indicating t
1350: 68 61 74 20 74 68 65 20 72 65 71 75 65 73 74 65  hat the requeste
1360: 64 0a 70 61 67 65 20 69 73 20 6e 6f 74 20 63 75  d.page is not cu
1370: 72 72 65 6e 74 6c 79 20 6d 61 70 70 65 64 20 69  rrently mapped i
1380: 6e 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74  nto the applicat
1390: 69 6f 6e 73 20 61 64 64 72 65 73 73 20 73 70 61  ions address spa
13a0: 63 65 29 20 74 68 65 6e 0a 53 51 4c 69 74 65 20  ce) then.SQLite 
13b0: 73 69 6c 65 6e 74 6c 79 20 66 61 6c 6c 73 20 62  silently falls b
13c0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 78 52 65  ack to using xRe
13d0: 61 64 28 29 2e 20 20 41 6e 20 65 72 72 6f 72 20  ad().  An error 
13e0: 69 73 20 6f 6e 6c 79 20 72 65 70 6f 72 74 65 64  is only reported
13f0: 0a 69 66 20 78 52 65 61 64 28 29 20 61 6c 73 6f  .if xRead() also
1400: 20 66 61 69 6c 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e   fails.</p>..<p>
1410: 57 68 65 6e 20 75 70 64 61 74 69 6e 67 20 74 68  When updating th
1420: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
1430: 20 53 51 4c 69 74 65 20 61 6c 77 61 79 73 20 6d   SQLite always m
1440: 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
1450: 68 65 0a 70 61 67 65 20 63 6f 6e 74 65 6e 74 20  he.page content 
1460: 69 6e 74 6f 20 68 65 61 70 20 6d 65 6d 6f 72 79  into heap memory
1470: 20 62 65 66 6f 72 65 20 6d 6f 64 69 66 79 69 6e   before modifyin
1480: 67 20 74 68 65 20 70 61 67 65 2e 20 20 54 68 69  g the page.  Thi
1490: 73 20 69 73 20 6e 65 63 65 73 73 61 72 79 0a 73  s is necessary.s
14a0: 69 6e 63 65 20 74 68 65 20 63 68 61 6e 67 65 73  ince the changes
14b0: 20 61 72 65 20 6e 6f 74 20 73 75 70 70 6f 73 65   are not suppose
14c0: 64 20 74 6f 20 62 65 20 76 69 73 69 62 6c 65 20  d to be visible 
14d0: 74 6f 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  to other process
14e0: 65 73 20 75 6e 74 69 6c 0a 61 66 74 65 72 20 74  es until.after t
14f0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  he transaction c
1500: 6f 6d 6d 69 74 73 20 61 6e 64 20 73 6f 20 74 68  ommits and so th
1510: 65 20 63 68 61 6e 67 65 73 20 6d 75 73 74 20 6f  e changes must o
1520: 63 63 75 72 20 69 6e 20 70 72 69 76 61 74 65 20  ccur in private 
1530: 6d 65 6d 6f 72 79 2e 0a 41 66 74 65 72 20 61 6c  memory..After al
1540: 6c 20 6e 65 65 64 65 64 20 63 68 61 6e 67 65 73  l needed changes
1550: 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2c 20   are completed, 
1560: 78 57 72 69 74 65 28 29 20 69 73 20 75 73 65 64  xWrite() is used
1570: 20 74 6f 20 6d 6f 76 65 20 74 68 65 20 63 6f 6e   to move the con
1580: 74 65 6e 74 0a 62 61 63 6b 20 69 6e 74 6f 20 74  tent.back into t
1590: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
15a0: 2e 20 20 54 68 65 20 63 75 72 72 65 6e 74 20 78  .  The current x
15b0: 57 72 69 74 65 28 29 20 69 6d 70 6c 65 6d 65 6e  Write() implemen
15c0: 74 61 74 69 6f 6e 73 20 66 6f 72 20 62 6f 74 68  tations for both
15d0: 0a 75 6e 69 78 20 61 6e 64 20 77 69 6e 64 6f 77  .unix and window
15e0: 73 20 63 68 65 63 6b 20 74 6f 20 73 65 65 20 69  s check to see i
15f0: 66 20 73 65 63 74 69 6f 6e 20 6f 66 20 74 68 65  f section of the
1600: 20 66 69 6c 65 20 62 65 69 6e 67 20 77 72 69 74   file being writ
1610: 74 65 6e 20 69 73 20 0a 6d 61 70 70 65 64 20 69  ten is .mapped i
1620: 6e 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74  nto the applicat
1630: 69 6f 6e 73 20 61 64 64 72 65 73 73 20 73 70 61  ions address spa
1640: 63 65 2c 20 61 6e 64 20 69 66 20 69 74 20 69 73  ce, and if it is
1650: 20 74 68 65 20 77 72 69 74 65 20 6f 70 65 72 61   the write opera
1660: 74 69 6f 6e 0a 69 73 20 69 6d 70 6c 65 6d 65 6e  tion.is implemen
1670: 74 65 64 20 75 73 69 6e 67 20 6d 65 6d 63 70 79  ted using memcpy
1680: 28 29 20 72 61 74 68 65 72 20 74 68 61 6e 20 69  () rather than i
1690: 6e 76 6f 6b 69 6e 67 20 61 20 22 77 72 69 74 65  nvoking a "write
16a0: 28 29 22 20 73 79 73 74 65 6d 20 63 61 6c 6c 2c  ()" system call,
16b0: 0a 62 75 74 20 74 68 61 74 20 69 73 20 6a 75 73  .but that is jus
16c0: 74 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  t an implementat
16d0: 69 6f 6e 20 64 65 74 61 69 6c 2e 20 20 41 20 6d  ion detail.  A m
16e0: 65 6d 6f 72 79 20 63 6f 70 79 20 6f 63 63 75 72  emory copy occur
16f0: 73 20 65 69 74 68 65 72 20 77 61 79 2e 0a 53 6f  s either way..So
1700: 20 74 68 65 20 75 73 65 20 6f 66 20 6d 65 6d 6f   the use of memo
1710: 72 79 20 6d 61 70 70 65 64 20 49 2f 4f 20 64 6f  ry mapped I/O do
1720: 65 73 20 6e 6f 74 20 73 69 67 6e 69 66 69 63 61  es not significa
1730: 6e 74 6c 79 20 63 68 61 6e 67 65 20 74 68 65 20  ntly change the 
1740: 70 65 72 66 6f 72 6d 61 6e 63 65 0a 6f 66 20 64  performance.of d
1750: 61 74 61 62 61 73 65 20 63 68 61 6e 67 65 73 2e  atabase changes.
1760: 20 20 4d 65 6d 6f 72 79 20 6d 61 70 70 65 64 20    Memory mapped 
1770: 49 2f 4f 20 69 73 20 6d 6f 73 74 6c 79 20 61 20  I/O is mostly a 
1780: 62 65 6e 65 66 69 74 20 66 6f 72 20 71 75 65 72  benefit for quer
1790: 69 65 73 2e 3c 2f 70 3e 0a 0a 3c 68 32 3e 43 6f  ies.</p>..<h2>Co
17a0: 6e 66 69 67 75 72 69 6e 67 20 4d 65 6d 6f 72 79  nfiguring Memory
17b0: 2d 4d 61 70 70 65 64 20 49 2f 4f 3c 2f 68 32 3e  -Mapped I/O</h2>
17c0: 0a 0a 3c 70 3e 54 68 65 20 22 6d 6d 61 70 5f 73  ..<p>The "mmap_s
17d0: 69 7a 65 22 20 69 73 20 74 68 65 20 6d 61 78 69  ize" is the maxi
17e0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
17f0: 74 65 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tes of the datab
1800: 61 73 65 20 66 69 6c 65 20 74 68 61 74 0a 53 51  ase file that.SQ
1810: 4c 69 74 65 20 77 69 6c 6c 20 74 72 79 20 74 6f  Lite will try to
1820: 20 6d 61 70 20 69 6e 74 6f 20 74 68 65 20 70 72   map into the pr
1830: 6f 63 65 73 73 20 61 64 64 72 65 73 73 20 73 70  ocess address sp
1840: 61 63 65 20 61 74 20 6f 6e 65 20 74 69 6d 65 2e  ace at one time.
1850: 20 20 54 68 65 0a 6d 6d 61 70 5f 73 69 7a 65 20    The.mmap_size 
1860: 61 70 70 6c 69 65 73 20 73 65 70 61 72 61 74 65  applies separate
1870: 6c 79 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ly to each datab
1880: 61 73 65 20 66 69 6c 65 2c 20 73 6f 20 74 68 65  ase file, so the
1890: 20 74 6f 74 61 6c 20 61 6d 6f 75 6e 74 0a 6f 66   total amount.of
18a0: 20 70 72 6f 63 65 73 73 20 61 64 64 72 65 73 73   process address
18b0: 20 73 70 61 63 65 20 74 68 61 74 20 63 6f 75 6c   space that coul
18c0: 64 20 70 6f 74 65 6e 74 69 61 6c 6c 79 20 62 65  d potentially be
18d0: 20 75 73 65 64 20 69 73 20 74 68 65 20 6d 6d 61   used is the mma
18e0: 70 5f 73 69 7a 65 0a 74 69 6d 65 73 20 74 68 65  p_size.times the
18f0: 20 6e 75 6d 62 65 72 20 6f 66 20 6f 70 65 6e 20   number of open 
1900: 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 3c  database files.<
1910: 2f 70 3e 0a 0a 3c 70 3e 54 6f 20 61 63 74 69 76  /p>..<p>To activ
1920: 61 74 65 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65  ate memory-mappe
1930: 64 20 49 2f 4f 2c 20 61 6e 20 61 70 70 6c 69 63  d I/O, an applic
1940: 61 74 69 6f 6e 20 63 61 6e 20 73 65 74 20 74 68  ation can set th
1950: 65 20 6d 6d 61 70 5f 73 69 7a 65 20 74 6f 20 73  e mmap_size to s
1960: 6f 6d 65 0a 6c 61 72 67 65 20 76 61 6c 75 65 2e  ome.large value.
1970: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 3c 2f    For example:</
1980: 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
1990: 3c 70 72 65 3e 0a 50 52 41 47 4d 41 20 6d 6d 61  <pre>.PRAGMA mma
19a0: 70 5f 73 69 7a 65 3d 32 36 38 34 33 35 34 35 36  p_size=268435456
19b0: 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  ;.</pre></blockq
19c0: 75 6f 74 65 3e 0a 0a 3c 70 3e 54 6f 20 64 69 73  uote>..<p>To dis
19d0: 61 62 6c 65 20 6d 65 6d 6f 72 79 2d 6d 61 70 70  able memory-mapp
19e0: 65 64 20 49 2f 4f 2c 20 73 69 6d 70 6c 79 20 73  ed I/O, simply s
19f0: 65 74 20 74 68 65 20 6d 6d 61 70 5f 73 69 7a 65  et the mmap_size
1a00: 20 74 6f 20 7a 65 72 6f 3a 3c 2f 70 3e 0a 0a 3c   to zero:</p>..<
1a10: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1a20: 0a 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  .PRAGMA mmap_siz
1a30: 65 3d 30 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  e=0;.</pre></blo
1a40: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 49 66 20  ckquote>..<p>If 
1a50: 6d 6d 61 70 5f 73 69 7a 65 20 69 73 20 73 65 74  mmap_size is set
1a60: 20 74 6f 20 4e 20 74 68 65 6e 20 61 6c 6c 20 63   to N then all c
1a70: 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
1a80: 61 74 69 6f 6e 73 20 6d 61 70 20 74 68 65 20 66  ations map the f
1a90: 69 72 73 74 0a 4e 20 62 79 74 65 73 20 6f 66 20  irst.N bytes of 
1aa0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
1ab0: 65 20 61 6e 64 20 75 73 65 20 6c 65 67 61 63 79  e and use legacy
1ac0: 20 78 52 65 61 64 28 29 20 63 61 6c 6c 73 20 66   xRead() calls f
1ad0: 6f 72 20 61 6e 79 20 63 6f 6e 74 65 6e 74 0a 62  or any content.b
1ae0: 65 79 6f 6e 64 20 4e 20 62 79 74 65 73 2e 20 20  eyond N bytes.  
1af0: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1b00: 66 69 6c 65 20 69 73 20 73 6d 61 6c 6c 65 72 20  file is smaller 
1b10: 74 68 61 6e 20 4e 20 62 79 74 65 73 2c 20 74 68  than N bytes, th
1b20: 65 6e 20 74 68 65 20 65 6e 74 69 72 65 0a 66 69  en the entire.fi
1b30: 6c 65 20 69 73 20 6d 61 70 70 65 64 2e 20 20 49  le is mapped.  I
1b40: 6e 20 74 68 65 20 66 75 74 75 72 65 2c 20 6e 65  n the future, ne
1b50: 77 20 4f 53 20 69 6e 74 65 72 66 61 63 65 73 20  w OS interfaces 
1b60: 63 6f 75 6c 64 2c 20 69 6e 20 74 68 65 6f 72 79  could, in theory
1b70: 2c 20 6d 61 70 0a 72 65 67 69 6f 6e 73 20 6f 66  , map.regions of
1b80: 20 74 68 65 20 66 69 6c 65 20 6f 74 68 65 72 20   the file other 
1b90: 74 68 61 6e 20 74 68 65 20 66 69 72 73 74 20 4e  than the first N
1ba0: 20 62 79 74 65 73 2c 20 62 75 74 20 6e 6f 20 73   bytes, but no s
1bb0: 75 63 68 20 0a 69 6d 70 6c 65 6d 65 6e 74 61 74  uch .implementat
1bc0: 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 65 78  ion currently ex
1bd0: 69 73 74 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68  ists.</p>..<p>Th
1be0: 65 20 6d 6d 61 70 5f 73 69 7a 65 20 69 73 20 73  e mmap_size is s
1bf0: 65 74 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f  et separately fo
1c00: 72 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  r each database 
1c10: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 22  file using the."
1c20: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
1c30: 65 5d 22 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  e]" statement.  
1c40: 54 68 65 20 75 73 75 61 6c 20 64 65 66 61 75 6c  The usual defaul
1c50: 74 20 6d 6d 61 70 5f 73 69 7a 65 20 69 73 20 7a  t mmap_size is z
1c60: 65 72 6f 2c 0a 6d 65 61 6e 69 6e 67 20 74 68 61  ero,.meaning tha
1c70: 74 20 6d 65 6d 6f 72 79 20 6d 61 70 70 65 64 20  t memory mapped 
1c80: 49 2f 4f 20 69 73 20 64 69 73 61 62 6c 65 64 20  I/O is disabled 
1c90: 62 79 20 64 65 66 61 75 6c 74 2e 20 20 48 6f 77  by default.  How
1ca0: 65 76 65 72 2c 20 74 68 65 0a 64 65 66 61 75 6c  ever, the.defaul
1cb0: 74 20 6d 6d 61 70 5f 73 69 7a 65 20 63 61 6e 20  t mmap_size can 
1cc0: 62 65 20 69 6e 63 72 65 61 73 65 64 20 65 69 74  be increased eit
1cd0: 68 65 72 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  her at compile-t
1ce0: 69 6d 65 20 75 73 69 6e 67 0a 74 68 65 20 5b 53  ime using.the [S
1cf0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 4d  QLITE_DEFAULT_MM
1d00: 41 50 5f 53 49 5a 45 5d 20 6d 61 63 72 6f 20 6f  AP_SIZE] macro o
1d10: 72 20 61 74 20 73 74 61 72 74 2d 74 69 6d 65 20  r at start-time 
1d20: 75 73 69 6e 67 20 74 68 65 0a 5b 73 71 6c 69 74  using the.[sqlit
1d30: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
1d40: 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
1d50: 49 5a 45 5d 2c 2e 2e 2e 29 20 69 6e 74 65 72 66  IZE],...) interf
1d60: 61 63 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e 53 51 4c  ace.</p>..<p>SQL
1d70: 69 74 65 20 61 6c 73 6f 20 6d 61 69 6e 74 61 69  ite also maintai
1d80: 6e 73 20 61 20 68 61 72 64 20 75 70 70 65 72 20  ns a hard upper 
1d90: 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 6d 6d 61  bound on the mma
1da0: 70 5f 73 69 7a 65 2e 20 20 41 74 74 65 6d 70 74  p_size.  Attempt
1db0: 73 0a 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68  s.to increase th
1dc0: 65 20 6d 6d 61 70 5f 73 69 7a 65 20 61 62 6f 76  e mmap_size abov
1dd0: 65 20 74 68 69 73 20 68 61 72 64 20 75 70 70 65  e this hard uppe
1de0: 72 20 62 6f 75 6e 64 20 28 75 73 69 6e 67 0a 5b  r bound (using.[
1df0: 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
1e00: 5d 29 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  ]) will automati
1e10: 63 61 6c 6c 79 20 63 61 70 20 74 68 65 20 6d 6d  cally cap the mm
1e20: 61 70 5f 73 69 7a 65 20 61 74 20 74 68 65 20 68  ap_size at the h
1e30: 61 72 64 0a 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard.upper bound.
1e40: 20 20 49 66 20 74 68 65 20 68 61 72 64 20 75 70    If the hard up
1e50: 70 65 72 20 62 6f 75 6e 64 20 69 73 20 7a 65 72  per bound is zer
1e60: 6f 2c 20 74 68 65 6e 20 6d 65 6d 6f 72 79 20 6d  o, then memory m
1e70: 61 70 70 65 64 20 49 2f 4f 0a 69 73 20 69 6d 70  apped I/O.is imp
1e80: 6f 73 73 69 62 6c 65 2e 20 20 54 68 65 20 68 61  ossible.  The ha
1e90: 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 63  rd upper bound c
1ea0: 61 6e 20 62 65 20 73 65 74 20 61 74 20 63 6f 6d  an be set at com
1eb0: 70 69 6c 65 2d 74 69 6d 65 20 75 73 69 6e 67 0a  pile-time using.
1ec0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  the [SQLITE_MAX_
1ed0: 4d 4d 41 50 5f 53 49 5a 45 5d 20 6d 61 63 72 6f  MMAP_SIZE] macro
1ee0: 2e 20 20 49 66 20 5b 53 51 4c 49 54 45 5f 4d 41  .  If [SQLITE_MA
1ef0: 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 69 73 20  X_MMAP_SIZE] is 
1f00: 73 65 74 20 74 6f 0a 7a 65 72 6f 2c 20 74 68 65  set to.zero, the
1f10: 6e 20 74 68 65 20 63 6f 64 65 20 75 73 65 64 20  n the code used 
1f20: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 6d 65 6d  to implement mem
1f30: 6f 72 79 20 6d 61 70 70 65 64 20 49 2f 4f 20 69  ory mapped I/O i
1f40: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 0a 74  s omitted from.t
1f50: 68 65 20 62 75 69 6c 64 2e 20 20 54 68 65 20 68  he build.  The h
1f60: 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
1f70: 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
1f80: 20 73 65 74 20 74 6f 20 7a 65 72 6f 20 6f 6e 20   set to zero on 
1f90: 63 65 72 74 61 69 6e 0a 70 6c 61 74 66 6f 72 6d  certain.platform
1fa0: 73 20 28 65 78 3a 20 4f 70 65 6e 42 53 44 29 20  s (ex: OpenBSD) 
1fb0: 77 68 65 72 65 20 6d 65 6d 6f 72 79 20 6d 61 70  where memory map
1fc0: 70 65 64 20 49 2f 4f 20 64 6f 65 73 20 6e 6f 74  ped I/O does not
1fd0: 20 77 6f 72 6b 20 64 75 65 20 74 6f 20 74 68 65   work due to the
1fe0: 0a 6c 61 63 6b 20 6f 66 20 61 20 75 6e 69 66 69  .lack of a unifi
1ff0: 65 64 20 62 75 66 66 65 72 20 63 61 63 68 65 2e  ed buffer cache.
2000: 3c 2f 70 3e 0a 0a 3c 70 3e 49 66 20 74 68 65 20  </p>..<p>If the 
2010: 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
2020: 20 6f 6e 20 6d 6d 61 70 5f 73 69 7a 65 20 69 73   on mmap_size is
2030: 20 6e 6f 6e 2d 7a 65 72 6f 20 61 74 20 63 6f 6d   non-zero at com
2040: 70 69 6c 61 74 69 6f 6e 20 74 69 6d 65 2c 0a 69  pilation time,.i
2050: 74 20 6d 61 79 20 73 74 69 6c 6c 20 62 65 20 72  t may still be r
2060: 65 64 75 63 65 64 20 6f 72 20 7a 65 72 6f 65 64  educed or zeroed
2070: 20 61 74 20 73 74 61 72 74 2d 74 69 6d 65 20 75   at start-time u
2080: 73 69 6e 67 20 74 68 65 0a 5b 73 71 6c 69 74 65  sing the.[sqlite
2090: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
20a0: 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
20b0: 5a 45 5d 2c 58 2c 59 29 20 69 6e 74 65 72 66 61  ZE],X,Y) interfa
20c0: 63 65 2e 20 20 54 68 65 20 58 20 61 6e 64 0a 59  ce.  The X and.Y
20d0: 20 70 61 72 61 6d 65 74 65 72 73 20 6d 75 73 74   parameters must
20e0: 20 62 6f 74 68 20 62 65 20 36 34 2d 62 69 74 20   both be 64-bit 
20f0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
2100: 20 54 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   The X parameter
2110: 0a 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20  .is the default 
2120: 6d 6d 61 70 5f 73 69 7a 65 20 6f 66 20 74 68 65  mmap_size of the
2130: 20 70 72 6f 63 65 73 73 20 61 6e 64 20 74 68 65   process and the
2140: 20 59 20 69 73 20 74 68 65 20 6e 65 77 20 68 61   Y is the new ha
2150: 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
2160: 54 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  The hard upper b
2170: 6f 75 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 69  ound cannot be i
2180: 6e 63 72 65 61 73 65 64 20 61 62 6f 76 65 20 69  ncreased above i
2190: 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ts compile-time 
21a0: 73 65 74 74 69 6e 67 0a 75 73 69 6e 67 20 5b 53  setting.using [S
21b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
21c0: 50 5f 53 49 5a 45 5d 20 62 75 74 20 69 74 20 63  P_SIZE] but it c
21d0: 61 6e 20 62 65 20 72 65 64 75 63 65 64 20 6f 72  an be reduced or
21e0: 20 7a 65 72 6f 65 64 2e 3c 2f 70 3e 0a            zeroed.</p>.