/ Check-in [0791f917]
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Added the 34to35.html document describing the changes between 3.4.2 and 3.5.0. Minor interface cleanups. (CVS 4302)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 0791f917bb18d7305b805b9cbcb308bdd7b3a1f5
User & Date: drh 2007-08-27 21:10:36
Context
2007-08-27
21:49
Bring the amalgamation builder up to date with the latest changes. Remove some vestigial code. (CVS 4303) check-in: 0ae30e5c user: drh tags: trunk
21:10
Added the 34to35.html document describing the changes between 3.4.2 and 3.5.0. Minor interface cleanups. (CVS 4302) check-in: 0791f917 user: drh tags: trunk
17:27
Modify sqlite3_release_memory() to use a global LRU list of pages. Untested. (CVS 4301) check-in: 5626ce0b user: danielk1977 tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to main.mk.

703
704
705
706
707
708
709



710
711
712
713
714
715
716
...
746
747
748
749
750
751
752
753

754
755
756
757
758
759
760

version3.html:	$(TOP)/www/version3.tcl
	tclsh $(TOP)/www/version3.tcl >version3.html

whentouse.html:	$(TOP)/www/whentouse.tcl
	tclsh $(TOP)/www/whentouse.tcl >whentouse.html





# Files to be published on the website.
#
DOC = \
  arch.html \
  autoinc.html \
  c_interface.html \
................................................................................
  sharedcache.html \
  speed.html \
  sqlite.html \
  support.html \
  tclsqlite.html \
  vdbe.html \
  version3.html \
  whentouse.html


doc:	common.tcl $(DOC)
	mkdir -p doc
	mv $(DOC) doc
	cp $(TOP)/www/*.gif $(TOP)/art/*.gif doc

# Standard install and cleanup targets







>
>
>







 







|
>







703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
...
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764

version3.html:	$(TOP)/www/version3.tcl
	tclsh $(TOP)/www/version3.tcl >version3.html

whentouse.html:	$(TOP)/www/whentouse.tcl
	tclsh $(TOP)/www/whentouse.tcl >whentouse.html

34to35.html:	$(TOP)/www/34to35.tcl
	tclsh $(TOP)/www/34to35.tcl >34to35.html


# Files to be published on the website.
#
DOC = \
  arch.html \
  autoinc.html \
  c_interface.html \
................................................................................
  sharedcache.html \
  speed.html \
  sqlite.html \
  support.html \
  tclsqlite.html \
  vdbe.html \
  version3.html \
  whentouse.html \
  34to35.html

doc:	common.tcl $(DOC)
	mkdir -p doc
	mv $(DOC) doc
	cp $(TOP)/www/*.gif $(TOP)/art/*.gif doc

# Standard install and cleanup targets

Changes to src/os_unix.c.

2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
  switch( flags ){
    case SQLITE_ACCESS_EXISTS:
      amode = F_OK;
      break;
    case SQLITE_ACCESS_READWRITE:
      amode = W_OK|R_OK;
      break;
    case SQLITE_ACCESS_READONLY:
      amode = R_OK;
      break;

    default:
      assert(!"Invalid flags argument");
  }
  return (access(zPath, amode)==0);







|







2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
  switch( flags ){
    case SQLITE_ACCESS_EXISTS:
      amode = F_OK;
      break;
    case SQLITE_ACCESS_READWRITE:
      amode = W_OK|R_OK;
      break;
    case SQLITE_ACCESS_READ:
      amode = R_OK;
      break;

    default:
      assert(!"Invalid flags argument");
  }
  return (access(zPath, amode)==0);

Changes to src/os_win.c.

1233
1234
1235
1236
1237
1238
1239

1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
    return SQLITE_NOMEM;
#else
    attr = GetFileAttributesA((char*)zConverted);
#endif
  }
  free(zConverted);
  switch( flags ){

    case SQLITE_ACCESS_EXISTS:
      rc = attr!=0xffffffff;
      break;
    case SQLITE_ACCESS_READWRITE:
      rc = (attr & FILE_ATTRIBUTE_READONLY)==0;
      break;
    case SQLITE_ACCESS_READONLY:
      rc = (attr!=0xffffffff) && ((attr & FILE_ATTRIBUTE_READONLY)==1);
      break;
    default:
      assert(!"Invalid flags argument");
  }
  return rc;
}









>






<
<
<







1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246



1247
1248
1249
1250
1251
1252
1253
    return SQLITE_NOMEM;
#else
    attr = GetFileAttributesA((char*)zConverted);
#endif
  }
  free(zConverted);
  switch( flags ){
    case SQLITE_ACCESS_READ:
    case SQLITE_ACCESS_EXISTS:
      rc = attr!=0xffffffff;
      break;
    case SQLITE_ACCESS_READWRITE:
      rc = (attr & FILE_ATTRIBUTE_READONLY)==0;
      break;



    default:
      assert(!"Invalid flags argument");
  }
  return rc;
}


Changes to src/sqlite.h.in.

26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
...
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
...
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
...
645
646
647
648
649
650
651












652
653
654
655
656
657
658
659
660
661
** on how SQLite interfaces are suppose to operate.
**
** The name of this file under configuration management is "sqlite.h.in".
** The makefile makes some minor changes to this file (such as inserting
** the version number) and changes its name to "sqlite3.h" as
** part of the build process.
**
** @(#) $Id: sqlite.h.in,v 1.243 2007/08/27 17:27:49 danielk1977 Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
#include <stdarg.h>     /* Needed for the definition of va_list */

/*
** Make sure we can call this stuff from C++.
................................................................................
**
** The zName field holds the name of the VFS module.  The name must
** be unique across all VFS modules.
**
** SQLite will guarantee that the zFilename string passed to
** xOpen() is a full pathname as generated by xFullPathname() and
** that the string will be valid and unchanged until xClose() is
** called.  So the sqlite3_file can store a pointer to the
** filename if it needs to remember the filename for some reason.
**
** The flags argument to xOpen() is a copy of the flags argument
** to sqlite3_open_v2().  If sqlite3_open() or sqlite3_open16()
** is used, then flags is SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE.
** If xOpen() opens a file read-only then it sets *pOutFlags to
** include SQLITE_OPEN_READONLY.  Other bits in *pOutFlags may be
................................................................................
** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
** deleted when it is closed.  This will always be set for TEMP 
** databases and journals and for subjournals.  The 
** [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
** for exclusive access.  This flag is set for all files except
** for the main database file.
** 
** The sqlite3_file structure passed as the third argument to
** xOpen is allocated by the caller.  xOpen just fills it in.  The
** caller allocates a minimum of szOsFile bytes for the sqlite3_file
** structure.
** 
** The flags argument to xAccess() may be 0 (to test for the
** existance of a file) or SQLITE_ACCESS_READWRITE to test to see
** if a file is readable and writable, or SQLITE_ACCESS_READONLY
** to test to see if a file is read-only.  The file can be a 
** directory.
** 
................................................................................
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  int (*xSleep)(sqlite3_vfs*, int microseconds);
  int (*xCurrentTime)(sqlite3_vfs*, double*);
  /* New fields may be appended in figure versions.  The iVersion
  ** value will increment whenever this happens. */
};













#define SQLITE_ACCESS_EXISTS    0
#define SQLITE_ACCESS_READWRITE 1
#define SQLITE_ACCESS_READONLY  2

/*
** CAPI3REF: Enable Or Disable Extended Result Codes
**
** This routine enables or disables the
** [SQLITE_IOERR_READ | extended result codes] feature.
** By default, SQLite API routines return one of only 26 integer







|







 







|







 







|
|
|
|







 







>
>
>
>
>
>
>
>
>
>
>
>


|







26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
...
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
...
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
...
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
** on how SQLite interfaces are suppose to operate.
**
** The name of this file under configuration management is "sqlite.h.in".
** The makefile makes some minor changes to this file (such as inserting
** the version number) and changes its name to "sqlite3.h" as
** part of the build process.
**
** @(#) $Id: sqlite.h.in,v 1.244 2007/08/27 21:10:36 drh Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
#include <stdarg.h>     /* Needed for the definition of va_list */

/*
** Make sure we can call this stuff from C++.
................................................................................
**
** The zName field holds the name of the VFS module.  The name must
** be unique across all VFS modules.
**
** SQLite will guarantee that the zFilename string passed to
** xOpen() is a full pathname as generated by xFullPathname() and
** that the string will be valid and unchanged until xClose() is
** called.  So the [sqlite3_file] can store a pointer to the
** filename if it needs to remember the filename for some reason.
**
** The flags argument to xOpen() is a copy of the flags argument
** to sqlite3_open_v2().  If sqlite3_open() or sqlite3_open16()
** is used, then flags is SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE.
** If xOpen() opens a file read-only then it sets *pOutFlags to
** include SQLITE_OPEN_READONLY.  Other bits in *pOutFlags may be
................................................................................
** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
** deleted when it is closed.  This will always be set for TEMP 
** databases and journals and for subjournals.  The 
** [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
** for exclusive access.  This flag is set for all files except
** for the main database file.
** 
** Space to hold the  [sqlite3_file] structure passed as the third 
** argument to xOpen is allocated by caller (the SQLite core). 
** szOsFile bytes are allocated for this object.  The xOpen method
** fills in the allocated space.
** 
** The flags argument to xAccess() may be 0 (to test for the
** existance of a file) or SQLITE_ACCESS_READWRITE to test to see
** if a file is readable and writable, or SQLITE_ACCESS_READONLY
** to test to see if a file is read-only.  The file can be a 
** directory.
** 
................................................................................
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  int (*xSleep)(sqlite3_vfs*, int microseconds);
  int (*xCurrentTime)(sqlite3_vfs*, double*);
  /* New fields may be appended in figure versions.  The iVersion
  ** value will increment whenever this happens. */
};

/*
** CAPI3REF: Flags for the xAccess VFS method
**
** These integer constants can be used as the third parameter to
** the xAccess method of an [sqlite3_vfs] object.  They determine
** the kind of what kind of permissions the xAccess method is
** looking for.  With SQLITE_ACCESS_EXISTS, the xAccess method
** simply checks to see if the file exists.  With SQLITE_ACCESS_READWRITE,
** the xAccess method checks to see if the file is both readable
** and writable.  With SQLITE_ACCESS_READ the xAccess method
** checks to see if the file is readable.
*/
#define SQLITE_ACCESS_EXISTS    0
#define SQLITE_ACCESS_READWRITE 1
#define SQLITE_ACCESS_READ      2

/*
** CAPI3REF: Enable Or Disable Extended Result Codes
**
** This routine enables or disables the
** [SQLITE_IOERR_READ | extended result codes] feature.
** By default, SQLite API routines return one of only 26 integer

Changes to src/test_async.c.

722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
...
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
*/
static int asyncAccess(sqlite3_vfs *pAsyncVfs, const char *zName, int flags){
  int ret;
  AsyncWrite *p;
  sqlite3_vfs *pVfs = (sqlite3_vfs *)pAsyncVfs->pAppData;

  assert(flags==SQLITE_ACCESS_READWRITE 
      || flags==SQLITE_ACCESS_READONLY 
      || flags==SQLITE_ACCESS_EXISTS 
  );

  pthread_mutex_lock(&async.queueMutex);
  ret = sqlite3OsAccess(pVfs, zName, flags);
  if( flags==SQLITE_ACCESS_EXISTS ){
    for(p=async.pQueueFirst; p; p = p->pNext){
................................................................................
      ){
        ret = 1;
      }
    }
  }
  ASYNC_TRACE(("ACCESS(%s): %s = %d\n", 
    flags==SQLITE_ACCESS_READWRITE?"read-write":
    flags==SQLITE_ACCESS_READONLY?"read-only":"exists"
    , zName, ret)
  );
  pthread_mutex_unlock(&async.queueMutex);
  return ret;
}

static int asyncGetTempName(sqlite3_vfs *pAsyncVfs, char *zBufOut){







|







 







|







722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
...
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
*/
static int asyncAccess(sqlite3_vfs *pAsyncVfs, const char *zName, int flags){
  int ret;
  AsyncWrite *p;
  sqlite3_vfs *pVfs = (sqlite3_vfs *)pAsyncVfs->pAppData;

  assert(flags==SQLITE_ACCESS_READWRITE 
      || flags==SQLITE_ACCESS_READ 
      || flags==SQLITE_ACCESS_EXISTS 
  );

  pthread_mutex_lock(&async.queueMutex);
  ret = sqlite3OsAccess(pVfs, zName, flags);
  if( flags==SQLITE_ACCESS_EXISTS ){
    for(p=async.pQueueFirst; p; p = p->pNext){
................................................................................
      ){
        ret = 1;
      }
    }
  }
  ASYNC_TRACE(("ACCESS(%s): %s = %d\n", 
    flags==SQLITE_ACCESS_READWRITE?"read-write":
    flags==SQLITE_ACCESS_READ?"read":"exists"
    , zName, ret)
  );
  pthread_mutex_unlock(&async.queueMutex);
  return ret;
}

static int asyncGetTempName(sqlite3_vfs *pAsyncVfs, char *zBufOut){

Added www/34to35.tcl.













































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
#
# Run this TCL script to generate HTML for the goals.html file.
#
set rcsid {$Id: 34to35.tcl,v 1.1 2007/08/27 21:10:36 drh Exp $}
source common.tcl
header {SQLite Changes From Version 3.4.2 To 3.5.0}

proc CODE {text} {
  puts "<blockquote><pre>"
  puts $text
  puts "</pre></blockquote>"
}
proc SYNTAX {text} {
  puts "<blockquote><pre>"
  set t2 [string map {& &amp; < &lt; > &gt;} $text]
  regsub -all "/(\[^\n/\]+)/" $t2 {</b><i>\1</i><b>} t3
  puts "<b>$t3</b>"
  puts "</pre></blockquote>"
}
proc IMAGE {name {caption {}}} {
  puts "<center><img src=\"$name\">"
  if {$caption!=""} {
    puts "<br>$caption"
  }
  puts "</center>"
}
proc PARAGRAPH {text} {
  # regsub -all "/(\[a-zA-Z0-9\]+)/" $text {<i>\1</i>} t2
  #regsub -all "\\*(\[^\n*\]+)\\*" $text {<tt><b><big>\1</big></b></tt>} t3
  regsub -all {\[([^]\n]+)\]} $text {<b>\1</b>} t3
  puts "<p>$t3</p>\n"
}
set level(0) 0
set level(1) 0
proc HEADING {n name {tag {}}} {
  if {$tag!=""} {
    puts "<a name=\"$tag\">"
  }
  global level
  incr level($n)
  for {set i [expr {$n+1}]} {$i<10} {incr i} {
    set level($i) 0
  }
  if {$n==0} {
    set num {}
  } elseif {$n==1} {
    set num $level(1).0
  } else {
    set num $level(1)
    for {set i 2} {$i<=$n} {incr i} {
      append num .$level($i)
    }
  }
  incr n 1
  puts "<h$n>$num $name</h$n>"
}

HEADING 0 {Moving From SQLite 3.4.2 to 3.5.0}

PARAGRAPH {
  SQLite version 3.5.0 introduces a new OS interface layer that
  is incompatible with all prior versions of SQLite.  In addition,
  a few existing interfaces have been generalized to work across all
  database connections within a process rather than just all
  connections within a thread.  The purpose of this article
  is to describe the changes to 3.5.0 in detail so that users
  of prior versions of SQLite can judge what, if any, effort will
  be required to upgrade to newer versions.
}

HEADING 1 {Overview Of Changes}

PARAGRAPH {
  A quick enumeration of the changes in SQLite version 3.5.0
  is provide here.  Subsequent sections will describe these
  changes in more detail.
}
PARAGRAPH {
  <ol>
  <li>The OS interface layer has been completely reworked:
  <ol type="a">
  <li>The [sqlite3_os_switch()] interface has been removed.</li>
  <li>The [SQLITE_ENABLE_REDEF_IO] compile-time flag no longer functions.
      I/O procedures are now always redefinable.</li>
  <li>Three new objects are defined for specifying I/O procedures:
      [sqlite3_vfs], [sqlite3_file], and [sqlite3_io_methods].</li>
  <li>Three new interfaces are used to create alternative OS interfaces:
      [sqlite3_vfs_register()], [sqlite3_vfs_unregister()], and
      [sqlite3_vfs_find()].</li>
  <li>A new interface has been added to provided additional control over
      the creation of new database connections: [sqlite3_open_v2()].
      The legacy interfaces of [sqlite3_open()] and
      [sqlite3_open16()] continue to be fully supported.</li>
  </ol></li>
  <li>The optional shared cache and memory management features that
      were introduced in version 3.3.0 can now be used across multiple
      threads within the same process.  Formerly, these extensions only
      applied to database connections operating within a single thread.
   <ol type="a">
   <li>The [sqlite3_enable_shared_cache()] interface now applies to all
       threads within a process, not to just the one thread in which it
       was run.</li>
   <li>The [sqlite3_soft_heap_limit()] interface now applies to all threads
       within a process, not to just the one thread in which it was run.</li>
   <li>The [sqlite3_release_memory()] interface will now attempt to reduce
       the memory usages across all database connections in all threads, not
       just connections in the thread where the interface is called.</li>
   <li>The [sqlite3_thread_cleanup()] interface has become a no-op.</li>
   </ol></li>
  <li>Restrictions on the use of the same database connection by multiple
      threads have been dropped.  It is now safe for
      multiple threads to use the same database connection at the same
      time.</li>
  <li>There is now a compile-time option that allows an application to
      define alternative malloc()/free() implementations without having
      to modify any core SQLite code.</li>
  <li>There is now a compile-time option that allows an application to
      define alternative mutex implementations without having
      to modify any core SQLite code.</li>
  </ol>
}
PARAGRAPH {
  Of these changes, only 1a and 2a through 2c are incompatibilities
  in any formal sense.
  But users who have previously made custom modifications to the
  SQLite source (for example to add a custom OS layer for embedded
  hardware) might find that these changes have a larger impact.
  On the other hand, an important goal of these changes is to make
  it much easier to customize SQLite for use on different operating
  systems. 
}

HEADING 1 {The OS Interface Layer}

PARAGRAPH {
  If your system defines a custom OS interface for SQLite or if you
  were using the (undocumented) [sqlite3_os_switch()]
  interface, then you will need to make modifications in order to
  upgrade to SQLite version 3.5.0.  This may seem painful at first
  glance.  But as you look more closely, you will probably discover
  that your changes are made smaller and easier to understand and manage
  by the new SQLite interface.  It is likely that your changes will
  now also work seamlessly with the SQLite amalgamation.  You will
  no longer need to make any changes to the code SQLite source code.
  All of your changes can be effected by application code and you can
  link against a standard, unmodified version of the SQLite amalgamation.
  Furthermore, the OS interface layer, which was formerly undocumented,
  is now an officially support interface for SQLite.  So you have
  some assurance that this will be a one-time change and that your
  new backend will continue to work in future versions of SQLite.
}

HEADING 2 {The Virtual File System Object}

PARAGRAPH {
  The new OS interface for SQLite is built around an object named
  [sqlite3_vfs].  The "vfs" standard for "Virtual File System".
  The sqlite3_vfs object is basically a structure containing pointers
  to functions that implement the primitive disk I/O operations that
  SQLite needs to perform in order to read and write databases.  
  In this article, we will often refer a sqlite3_vfs objects as a "VFS".
}

PARAGRAPH {
  SQLite is able to use multiple VFSes at the same time.  Each
  individual database connection is associated with just one VFS.
  But if you have multiple database connections, each connection
  can be associated with a different VFS.
}

PARAGRAPH {
  There is always a default VFS.
  The legacy interfaces [sqlite3_open()] and [sqlite3_open16()] always
  use the default VFS.
  The new interface for creating database connections,
  [sqlite3_open_v2()], allows you to specify which VFS you want to
  use by name.
}

HEADING 3 {Registering New VFS Objects}

PARAGRAPH {
  Standard builds of SQLite for unix or windows come with a single
  VFS named "unix" or "win32", as appropriate.  This one VFS is also 
  the default.  So if you are using the legacy open functions, everything
  will continue to operate as it has before.  The change is that an application
  now has the flexibility of adding new VFS modules to implement a
  customized OS layer.  The [sqlite3_vfs_register()] API can be used
  to tell SQLite about one or more application-defined VFS modules:
}

CODE {
int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
}

PARAGRAPH {
  Applications can call sqlite3_vfs_register at any time, though of course
  a VFS needs to be registered before it can be used.  The first argument
  is a pointer to a customized VFS object that the application has prepared.
  The second argument is true to make the new VFS the default VFS so that
  it will be used by the legacy [sqlite3_open()] and [sqlite3_open16()] APIs.
  If the new VFS is not the default, then you will probably have to use
  the new [sqlite3_open_v2()] API to use it.  Note, however, that if
  a new VFS is the only VFS known to SQLite (if SQLite was compiled without
  its usual default VFS or if the pre-compiled default VFS was removed
  using [sqlite3_vfs_unregister()]) then the new VFS automatic becomes the
  default VFS regardless of the makeDflt argument to [sqlite3_vfs_register()].
}

PARAGRAPH {
  Standard builds include the default "unix" or "win32" VFSes.
  But if you use the -DOS_OTHER=1 compile-time option, then SQLite is
  built without a default VFS.  In that case, the application must
  register at least one VFS prior to calling [sqlite3_open()].
  This is the approach that embedded applications should use.
  Rather than modifying the SQLite source to to insert an alternative
  OS layer as was done in prior releases of SQLite, instead compile
  an unmodified SQLite source file (preferably the amalgamation)
  with the -DOS_OTHER=1 option, then invoke [sqlite3_vfs_register()]
  to define the interface to the underlying filesystem prior to
  creating any database connections.
}

HEADING 3 {Additional Control Over VFS Objects}

PARAGRAPH {
  The [sqlite3_vfs_unregister()] API is used to remove an existing
  VFS from the system.
}

CODE {
int sqlite3_vfs_unregister(sqlite3_vfs*);
}

PARAGRAPH {
  The [sqlite3_vfs_find()] API is used to locate a particular VFS
  by name.  Its prototype is as follows:
}

CODE {
sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
}

PARAGRAPH {
  The argument is the symbolic name for the desired VFS.  If the
  argument is a NULL pointer, then the default VFS is returned.
  The function returns a pointer to the [sqlite3_vfs] object that
  implements the VFS.  Or it returns a NULL pointer if no object
  could be found that matched the search criteria.
}

HEADING 3 {Modifications Of Existing VFSes}

PARAGRAPH {
  Once a VFS has been registered, it should never be modified.  If
  a change in behavior is required, a new VFS should be registered.
  The application could, perhaps, use [sqlite3_vfs_find()] to locate
  the old VFS, make a copy of the old VFS into a new [sqlite3_vfs]
  object, make the desired modifications to the new VFS, unregister
  the old VFS, the register the new VFS in its place.  Existing
  database connections would continue to use the old VFS even after
  it is unregistered, but new database connections would use the
  new VFS.
}  

HEADING 3 {The VFS Object}

PARAGRAPH {
  A VFS object is an instance of the following structure:
}

CODE {
typedef struct sqlite3_vfs sqlite3_vfs;
struct sqlite3_vfs {
  int iVersion;            /* Structure version number */
  int szOsFile;            /* Size of subclassed sqlite3_file */
  int mxPathname;          /* Maximum file pathname length */
  sqlite3_vfs *pNext;      /* Next registered VFS */
  const char *zName;       /* Name of this virtual file system */
  void *pAppData;          /* Pointer to application-specific data */
  int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
               int flags, int *pOutFlags);
  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags);
  int (*xGetTempName)(sqlite3_vfs*, char *zOut);
  int (*xFullPathname)(sqlite3_vfs*, const char *zName, char *zOut);
  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
  void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);
  void (*xDlClose)(sqlite3_vfs*, void*);
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  int (*xSleep)(sqlite3_vfs*, int microseconds);
  int (*xCurrentTime)(sqlite3_vfs*, double*);
  /* New fields may be appended in figure versions.  The iVersion
  ** value will increment whenever this happens. */
};
}

PARAGRAPH {
  To create a new VFS, an application fills in an instance of this
  structure with appropriate values and then calls [sqlite3_vfs_register()].
}

PARAGRAPH {
  The iVersion field of [sqlite3_vfs] should be 1 for SQLite version 3.5.0.
  This number may increase in future versions of SQLite if we have to
  modify the VFS object in some way.  We hope that this never happens,
  but the provision is made in case it does.
}

PARAGRAPH {
  The szOsFile field is the size in bytes of the structure that defines
  an open file: the [sqlite3_file] object.  This object will be described
  more fully below.  The point here is that each VFS implementation can
  define its own [sqlite3_file] object containing whatever information
  the VFS implementation needs to store about an open file.  SQLite needs
  to know how big this object is, however, in order to preallocate enough
  space to hold it.
}

PARAGRAPH {
  The mxPathname field is the maximum length of a file pathname that
  this VFS can use.  SQLite sometimes has to preallocate buffers of
  this size, so it should be as small as reasonably possible.  Some
  filesystems permit huge pathnames, but in practice pathnames rarely
  extend beyond 100 bytes or so.  You do not have to put the longest
  pathname that the underlying filesystem can handle here.  You only
  have to put the longest pathname that you want SQLite to be able to
  handle.  A few hundred is a good value in most cases.
}

PARAGRAPH {
  The pNext field is used internally by SQLite.  Specifically, SQLite
  uses this field to form a linked list of registered VFSes.
}

PARAGRAPH {
  The zName field is the symbolic name of the VFS.  This is the name 
  that the [sqlite3_vfs_find()] compares against when it is looking for
  a VFS.
}

PARAGRAPH {
  The pAppData pointer is unused by the SQLite core.  The pointer is
  available to store auxiliary information that a VFS information might
  want to carry around.
}

PARAGRAPH {
  The remaining fields of the [sqlite3_vfs] object all store pointer
  to functions that implement primitive operations.  We call these
  "methods".  The first methods, xOpen, is used to open files on
  the underlying storage media.  The result is an [sqlite3_file]
  object.  There are additional methods, defined by the [sqlite3_file]
  object itself that are used to read and write and close the file.
  The additional methods are detailed below.  The filename is in UTF-8.
  SQLite will guarantee that the zFilename string passed to
  xOpen() is a full pathname as generated by xFullPathname() and
  that the string will be valid and unchanged until xClose() is
  called.  So the [sqlite3_file] can store a pointer to the
   filename if it needs to remember the filename for some reason.
   The flags argument to xOpen() is a copy of the flags argument
   to sqlite3_open_v2().  If sqlite3_open() or sqlite3_open16()
   is used, then flags is SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE.
   If xOpen() opens a file read-only then it sets *pOutFlags to
   include SQLITE_OPEN_READONLY.  Other bits in *pOutFlags may be
   set.
   SQLite will also add one of the following flags to the xOpen()
   call, depending on the object being opened:
   <ul>
   <li>  [SQLITE_OPEN_MAIN_DB]
   <li>  [SQLITE_OPEN_MAIN_JOURNAL]
   <li>  [SQLITE_OPEN_TEMP_DB]
   <li>  [SQLITE_OPEN_TEMP_JOURNAL]
   <li>  [SQLITE_OPEN_SUBJOURNAL]
   <li>  [SQLITE_OPEN_MASTER_JOURNAL]
   </ul>
   The file I/O implementation can use the object type flags to
   changes the way it deals with files.  For example, an application
   that does not care about crash recovery or rollback, might make
   the open of a journal file a no-op.  Writes to this journal are
   also a no-op.  Any attempt to read the journal return SQLITE_IOERR.
   Or the implementation might recognize the a database file will
   be doing page-aligned sector reads and writes in a random order
   and set up its I/O subsystem accordingly.
   SQLite might also add one of the following flags to the xOpen
   method:
   <ul>
   <li> [SQLITE_OPEN_DELETEONCLOSE]
   <li> [SQLITE_OPEN_EXCLUSIVE]
   </ul>
   The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
   deleted when it is closed.  This will always be set for TEMP 
   databases and journals and for subjournals.  The 
   [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
   for exclusive access.  This flag is set for all files except
   for the main database file.
   The [sqlite3_file] structure passed as the third argument to
   xOpen is allocated by the caller.  xOpen just fills it in.  The
   caller allocates a minimum of szOsFile bytes for the [sqlite3_file]
   structure.
}

PARAGRAPH {
  The xDelete method is used delete a file.  The name of the file is
  given in the second parameter.  The filename will be in UTF-8.
  The VFS must convert the filename into whatever character representation
  the underlying operating system expects.  If the syncDir parameter is
  true, then the xDelete method should not return until the change
  to the directory contents for the directory containing the
  deleted file have been synced to disk in order to insure that the
  file does not "reappear" if a power failure occurs soon after.
}

PARAGRAPH {
  The xAccess method is used to check for access permissions on a file.
  The filename will be UTF-8 encoded.  The flags argument will be
  SQLITE_ACCESS_EXISTS to check for the existence of the file,
  SQLITE_ACCESS_READWRITE to check to see if the file is both readable
  and writable, or SQLITE_ACCESS_READ to check to see if the file is
  at least readable.  The "file" named by the second parameter might
  be a directory or folder name.
}

PARAGRAPH {
  The xGetTempName method computes the name of a temporary file that
  SQLite can use.  The name should be written into the buffer given
  by the second parameter.  SQLite will size that buffer to hold
  at least mxPathname bytes.  The generated filename should be in UTF-8.
  To avoid security problems, the generated temporary filename should
  contain enough randomness to prevent an attacker from guessing the
  temporary filename in advance.
}

PARAGRAPH {
  The xFullPathname method is used to convert a relative pathname
  into a full pathname.  The resulting full pathname is written into
  the buffer provided by the third parameter.  SQLite will size the
  output buffer to at least mxPathname bytes.  Both the input and
  output names should be in UTF-8.
}

PARAGRAPH {
  The xDlOpen, xDlError, xDlSym, and xDlClose methods are all used for
  accessing shared libraries at run-time.  These methods may be omitted
  (and their pointers set to zero) if the library is compiled with
  SQLITE_OMIT_LOAD_EXTENSION or if the [sqlite3_enable_load_extension()]
  interface is never used to enable dynamic extension loading.  The
  xDlOpen method opens a shared library or DLL and returns a pointer to
  a handle.  NULL is returned if the open fails.  If the open fails,
  the xDlError method can be used to obtain a text error message.
  The message is written into the zErrMsg buffer of the third parameter
  which is at least nByte bytes in length.  The xDlSym returns a pointer
  to a symbol in the shared library.  The name of the symbol is given
  by the second parameter.  UTF-8 encoding is assumed.  If the symbol
  is not found a NULL pointer is returned.  The xDlClose routine closes
  the shared library.
}

PARAGRAPH {
  The xRandomness method is used once by the first database connection
  that is opened.  xRandomness should return high-quality randomness
  that SQLite will used to seeds its internal pseudo-random number
  generator (PRNG).  The routine requests that nByte bytes of randomness
  be written into zOut.  The routine returns the actual number of
  bytes of randomness obtained.  The quality of the randomness so obtained
  will determine the quality of the randomness generated by built-in 
  SQLite functions such as random() and randomblob().
}

PARAGRAPH {
  The xSleep method is used to suspend the calling thread for at
  least the number of microseconds given.  This method is used to
  implement the [sqlite3_sleep()] and [sqlite3_busy_timeout()] APIs.
  In the case of [sqlite3_sleep()] the xSleep method of the default
  VFS is always used.  If the underlying system does not have a
  microsecond resolution sleep capability, then the sleep time should
  be rounded up.  xSleep returns this rounded-up value.
}

PARAGRAPH {
  The xCurrentTime method finds the current time and date and writes
  the result as double-precision floating point value into pointer
  provided by the second parameter.  The time and date is in
  coordinated universal time (UTC) and is a fractional julian day number.
}

HEADING 3 {The Open File Object}

PARAGRAPH {
  The result of opening a file is an instance of an [sqlite3_file] object.
  The [sqlite3_file] object is an abstract base class defined as follows:
}

CODE {
typedef struct sqlite3_file sqlite3_file;
struct sqlite3_file {
  const struct sqlite3_io_methods *pMethods;
};
}

PARAGRAPH {
  Each VFS implementation will subclass the [sqlite3_file] by adding
  additional fields at the end to hold whatever information the VFS
  needs to know about an open file.  It does not matter what information
  is stored as long as the total size of the structure does not exceed
  the szOsFile value recorded in the [sqlite3_vfs] object.
}

PARAGRAPH {
  The [sqlite3_io_methods] object is a structure that contains pointers
  to methods for reading, writing, and otherwise dealing with files.
  This object is defined as follows:
}

CODE {
typedef struct sqlite3_io_methods sqlite3_io_methods;
struct sqlite3_io_methods {
  int iVersion;
  int (*xClose)(sqlite3_file*);
  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite_int64 iOfst);
  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite_int64 iOfst);
  int (*xTruncate)(sqlite3_file*, sqlite_int64 size);
  int (*xSync)(sqlite3_file*, int flags);
  int (*xFileSize)(sqlite3_file*, sqlite_int64 *pSize);
  int (*xLock)(sqlite3_file*, int);
  int (*xUnlock)(sqlite3_file*, int);
  int (*xCheckReservedLock)(sqlite3_file*);
  int (*xBreakLock)(sqlite3_file*);
  int (*xLockState)(sqlite3_file *);
  int (*xSectorSize)(sqlite3_file*);
  int (*xDeviceCharacteristics)(sqlite3_file*);
  /* Additional methods may be added in future releases */
};
}

PARAGRAPH {
  The iVersion field of [sqlite3_io_methods] is provided as insurance
  against future enhancements.  The iVersion value should always be
  1 for SQLite version 3.5.
}

PARAGRAPH {
  The xClose method closes the file.  The space for the [sqlite3_file]
  structure is deallocated by the caller.  But if the [sqlite3_file]
  contains pointers to other allocated memory or resources, those
  allocations should be released by the xClose method.
}

PARAGRAPH {
  The xRead method reads iAmt bytes from the file beginning at a byte
  offset to iOfst.  The data read is stored in the pointer of the
  second parameter.  xRead returns the SQLITE_OK on success,
  SQLITE_IOERR_SHORT_READ if it was not able to read the full number
  of bytes because it reached end-of-file, or SQLITE_IOERR_READ for
  any other error.
}

PARAGRAPH {
  The xWrite method writes iAmt bytes of data from the second parameter
  into the file beginning at an offset of iOfst bytes.  If the size of
  the file is less than iOfst bytes prior to the write, then xWrite should
  ensure that the file is extended with zeros up to iOfst bytes prior
  to beginning its write.  xWrite continues to extends the file as
  necessary so that the size of the file is at least iAmt+iOfst bytes 
  at the conclusion of the xWrite call.  The xWrite method returns
  SQLITE_OK on success.  If the write cannot complete because the
  underlying storage medium is full, then SQLITE_FULL is returned.
  SQLITE_IOERR_WRITE should be returned for any other error.
}

PARAGRAPH {
  The xTruncate method truncates a file to be nByte bytes in length.
  If the file is already nByte bytes or less in length then this
  method is a no-op.  The xTruncate method returns SQLITE_OK on
  success and SQLITE_IOERR_TRUNCATE if anything goes wrong.
}

PARAGRAPH {
  The xSync method is used to force previously written data out of
  operating system cache and into non-volatile memory.  The second
  parameter is usually SQLITE_SYNC_NORMAL.  If the second parameter
  is SQLITE_SYNC_FULL then the xSync method should make sure that
  data has also been flushed through the disk controllers cache.
  The SQLITE_SYNC_FULL parameter is the equivalent of the F_FULLSYNC
  ioctl() on Mac OS X.  The SQLITE_SYNC_BARRIER is currently unused.
  In the future this value might request that the xSync call serve
  as an I/O barrier operation.  All write requests that occur before
  the xSync must complete before any write request that occurs
  afterwards, but the barrier does not require that all writes 
  complete prior to the return of xSync.  The xSync method returns
  SQLITE_OK on success and SQLITE_IOERR_FSYNC if anything goes wrong.
}

PARAGRAPH {
  The xFileSize() method determines the current size of the file
  in bytes and writes that value into *pSize.  It returns SQLITE_OK
  on success and SQLITE_IOERR_FSTAT if something goes wrong.
}

PARAGRAPH {
  The xLock and xUnlock methods are used to set and clear file locks.
  SQLite supports five levels of file locks, in order:
  <ul>
  <li> [SQLITE_LOCK_NONE]
  <li> [SQLITE_LOCK_SHARED]
  <li> [SQLITE_LOCK_RESERVED]
  <li> [SQLITE_LOCK_PENDING]
  <li> [SQLITE_LOCK_EXCLUSIVE]
  </ul>
  The underlying implementation can support some subset of these locking
  levels as long as it meets the other requirements of this paragraph.
  The locking level is specified as the second argument to both xLock
  and xUnlock.  The xLock method increases the locking level to the
  specified locking level or higher.  The xUnlock method decreases the
  locking level to no lower than the level specified.  
  SQLITE_LOCK_NONE means that the file is unlocked.  SQLITE_LOCK_SHARED
  gives permission to read the file.  Multiple database connections can
  hold SQLITE_LOCK_SHARED at the same time.
  SQLITE_LOCK_RESERVED is like SQLITE_LOCK_SHARED in that its is permission
  to read the file.  But only a single connection can hold a reserved lock
  at any point in time.  The SQLITE_LOCK_PENDING is also permission to
  read the file.  Other connections can continue to read the file as well,
  but no other connection is allowed to escalate a lock from none to shared.
  SQLITE_LOCK_EXCLUSIVE is permission to write on the file.  Only a single
  connection can hold an exclusive lock and no other connection can hold
  any lock (other than "none") while one connection is hold an exclusive
  lock.  The xLock returns SQLITE_OK on success, SQLITE_BUSY if it
  is unable to obtain the lock, or SQLITE_IOERR_RDLOCK if something else
  goes wrong.  The xUnlock method returns SQLITE_OK on success and
  SQLITE_IOERR_UNLOCK for problems.
}

PARAGRAPH {
  The xCheckReservedLock method checks to see if another connection or
  another process is currently holding a reserved, pending, or exclusive
  lock on the file.  It returns true or false.
}

PARAGRAPH {
  The xLockState method returns one of the [SQLITE_LOCK_NONE] through
  [SQLITE_LOCK_EXCLUSIVE] constants defined above to indicate the current
  state of the lock for the given file handle.  This method is used for
  testing purposes only.
}

PARAGRAPH {
  The xSectorSize returns the "sector size" of the underlying
  non-volatile media.  A "sector" is defined as the smallest unit of
  storage that can be written without disturbing adjacent storage.
  On a disk drive the "sector size" has until recently been 512 bytes,
  though there is a push to increase this value to 4KiB.  SQLite needs
  to know the sector size so that it can write a full sector at a
  time, and thus avoid corrupting adjacent storage space if a power
  lose occurs in the middle of a write.
}

PARAGRAPH {
  The xDeviceCharacteristics method returns an integer bit vector that
  defines any special properties that the underlying storage medium might
  have that SQLite can use to increase performance.  The allowed return
  is the bit-wise OR of the following values:
  <ul>
  <li> SQLITE_IOCAP_ATOMIC
  <li> SQLITE_IOCAP_ATOMIC512
  <li> SQLITE_IOCAP_ATOMIC1K
  <li> SQLITE_IOCAP_ATOMIC2K
  <li> SQLITE_IOCAP_ATOMIC4K
  <li> SQLITE_IOCAP_ATOMIC8K
  <li> SQLITE_IOCAP_ATOMIC16K
  <li> SQLITE_IOCAP_ATOMIC32K
  <li> SQLITE_IOCAP_ATOMIC64K
  <li> SQLITE_IOCAP_SAFE_APPEND
  <li> SQLITE_IOCAP_SEQUENTIAL
  </ul>
  The SQLITE_IOCAP_ATOMIC bit means that all writes to this device are
  atomic in the sense that either the entire write occurs or none of it
  occurs.  The other SQLITE_IOCAP_ATOMIC<i>nnn</i> values indicate that
  writes of aligned blocks of the indicated size are atomic.
  SQLITE_IOCAP_SAFE_APPEND means that when extending a file with new
  data, the new data is written first and then the file size is updated.
  So if a power failure occurs, there is no chance that the file might have
  been extended with randomness.  The SQLITE_IOCAP_SEQUENTIAL bit means
  that all writes occur in the order that they are issued and are not
  reordered by the underlying file system.
}

HEADING 3 {Checklist For Constructing A New VFS}

PARAGRAPH {
  The preceding paragraphs contain a lot of information.
  To ease the task of constructing
  a new VFS for SQLite we offer the following implementation checklist:
}

PARAGRAPH {
  <ol>
  <li> Define an appropriate subclass of the [sqlite3_file] object.
  <li> Implement the methods required by the [sqlite_io_methods] object.
  <li> Create a static and 
       constant [sqlite3_io_methods] object containing pointers
       to the methods from the previous step.
  <li> Implement the xOpen method that opens a file and populates an
       [sqlite3_file] object, including setting pMethods to
       point to the [sqlite3_io_methods] object from the previous step.
  <li> Implement the other methods required by [sqlite3_vfs].
  <li> Define a static (but not constant) [sqlite3_vfs] structure that
       contains pointers to the xOpen method and the other methods and
       which contains the appropriate values for iVersion, szOsFile,
       mxPathname, zName, and pAppData.
  <li> Implement a procedure that calls [sqlite3_vfs_register()] and
       passes it a pointer to the [sqlite3_vfs] structure from the previous
       step.  This procedure is probably the only exported symbol in the
       source file that implements your VFS.
  </ol>
}

PARAGRAPH {
  Within your application, call the procedure implemented in the last
  step above as part of your initialization process before any
  database connections are opened.  
}

HEADING 1 {The Memory Allocation Subsystem}

PARAGRAPH {
  Beginning with version 3.5, SQLite obtains all of the heap memory it
  needs using the routines [sqlite3_malloc()], [sqlite3_free()], and
  [sqlite3_realloc()].  These routines have existed in prior versions
  of SQLite, but SQLite has previously bypassed these routines and used
  its own memory allocator.  This all changes in version 3.5.0.
}

PARAGRAPH {
  The SQLite source tree actually contains multiple versions of the
  memory allocator.  The default high-speed version found in the
  "mem1.c" source file is used for most builds.  But if the SQLITE_MEMDEBUG
  flag is enabled, a separate memory allocator the "mem2.c" source file
  is used instead.  The mem2.c allocator implements lots of hooks to
  do error checking and to simulate memory allocation failures for testing
  purposes.  Both of these allocators use the malloc()/free() implementation
  in the standard C library.
}

PARAGRAPH {
  Applications are not required to use either of these standard memory
  allocators.  If SQLite is compiled with SQLITE_OMIT_MEMORY_ALLOCATION
  then no implementation for the [sqlite3_malloc()], [sqlite3_realloc()],
  and [sqlite3_free()] functions is provided.  Instead, the application
  that links against SQLite must provide its own implementation of these
  functions.  The application provided memory allocator is not required
  to use the malloc()/free() implementation in the standard C library.
  An embedded application might provide an alternative memory allocator
  that uses memory for a fixed memory pool set aside for the exclusive
  use of SQLite, for example.
}

PARAGRAPH {
  Applications that implement their own memory allocator must provide
  implementation for the usual three allocation functions 
  [sqlite3_malloc()], [sqlite3_realloc()], and [sqlite3_free()].
  And they must also implement a fourth function:
}

CODE {
int sqlite3_memory_alarm(
  void(*xCallback)(void *pArg, sqlite3_int64 used, int N),
  void *pArg,
  sqlite3_int64 iThreshold
);
}

PARAGRAPH {
 The [sqlite3_memory_alarm] routine is used to register
 a callback on memory allocation events.
 This routine registers or clears a callbacks that fires when
 the amount of memory allocated exceeds iThreshold.  Only
 a single callback can be registered at a time.  Each call
 to [sqlite3_memory_alarm()] overwrites the previous callback.
 The callback is disabled by setting xCallback to a NULL
 pointer.
}

PARAGRAPH {
 The parameters to the callback are the pArg value, the 
 amount of memory currently in use, and the size of the
 allocation that provoked the callback.  The callback will
 presumably invoke [sqlite3_free()] to free up memory space.
 The callback may invoke [sqlite3_malloc()] or [sqlite3_realloc()]
 but if it does, no additional callbacks will be invoked by
 the recursive calls.
}

PARAGRAPH {
 The [sqlite3_soft_heap_limit()] interface works by registering
 a memory alarm at the soft heap limit and invoking 
 [sqlite3_release_memory()] in the alarm callback.  Application
 programs should not attempt to use the [sqlite3_memory_alarm()]
 interface because doing so will interfere with the
 [sqlite3_soft_heap_limit()] module.  This interface is exposed
 only so that applications can provide their own
 alternative implementation when the SQLite core is
 compiled with SQLITE_OMIT_MEMORY_ALLOCATION.
}

PARAGRAPH {
  The built-in memory allocators in SQLite also provide the following
  additional interfaces:
}

CODE {
sqlite3_int64 sqlite3_memory_used(void);
sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
}

PARAGRAPH {
  These interfaces can be used by an application to monitor how
  much memory SQLite is using.  The [sqlite3_memory_used()] routine
  returns the number of bytes of memory currently in use and the
  [sqlite3_memory_highwater()] returns the maximum instantaneous
  memory usage.  Neither routine includes the overhead associated
  with the memory allocator.  These routines are provided for use
  by the application.  SQLite never invokes them itself.  So if
  the application is providing its own memory allocation subsystem,
  it can omit these interfaces if desired.
}

HEADING 1 {The Mutex Subsystem}

PARAGRAPH {
  SQLite has always been threadsafe in the sense that it is safe to
  use different SQLite database connections in different threads at the
  same time.  The constraint was that the same database connection
  could not be used in two separate threads at once.  SQLite version 3.5.0
  relaxes this constraint. 
}

PARAGRAPH {
  In order to allow multiple threads to use the same database connection
  at the same time, SQLite must make extensive use of mutexes.  And for
  this reason a new mutex subsystem as been added.  The mutex subsystem
  as the following interface:
}

CODE {
sqlite3_mutex *sqlite3_mutex_alloc(int);
void sqlite3_mutex_free(sqlite3_mutex*);
void sqlite3_mutex_enter(sqlite3_mutex*);
int sqlite3_mutex_try(sqlite3_mutex*);
void sqlite3_mutex_leave(sqlite3_mutex*);
}

PARAGRAPH {
  Though these routines exist for the use of the SQLite core, 
  application code is free to use these routines as well, if desired.
  A mutex is an [sqlite3_mutex] object.  The [sqlite3_mutex_alloc()]
  routine allocates a new mutex object and returns a pointer to it.
  The argument to [sqlite3_mutex_alloc()] should be 
  [SQLITE_MUTEX_FAST] or [SQLITE_MUTEX_RECURSIVE] for non-recursive
  and recursive mutexes, respectively.  If the underlying system does
  not provide non-recursive mutexes, then a recursive mutex can be
  substituted in that case.  The argument to [sqlite3_mutex_alloc()]
  can also be a constant designating one of several static mutexes:
  <ul>
  <li>  SQLITE_MUTEX_STATIC_MASTER
  <li>  SQLITE_MUTEX_STATIC_MEM
  <li>  SQLITE_MUTEX_STATIC_MEM2
  <li>  SQLITE_MUTEX_STATIC_PRNG
  </ul>
  These static mutexes are reserved for use internally by SQLite
  and should not be used by the application.  The static mutexes
  are all non-recursive.
}

PARAGRAPH {
  The [sqlite3_mutex_free()] routine should be used to deallocate
  a non-static mutex.  If a static mutex is passed to this routine
  then the behavior is undefined.
}

PARAGRAPH {
  The [sqlite3_mutex_enter()] attempts to enter the mutex and blocks
  if another threads is already there.  [sqlite3_mutex_try()] attempts
  to enter and returns SQLITE_OK on success or SQLITE_BUSY if another
  thread is already there.  [sqlite3_mutex_leave()] exits a mutex.
  The mutex is held until the number of exits matches the number of
  entrances.  If [sqlite3_mutex_leave()] is called on a mutex that 
  the thread is not currently holding, then the behavior is undefined.
  If any routine is called for a deallocated mutex, then the behavior
  is undefined.
}

PARAGRAPH {
  The SQLite source code provides multiple implementations of these
  APIs, suitable for varying environments.  If SQLite is compiled with
  the SQLITE_THREADSAFE=0 flag then a no-op mutex implementation that 
  is fast but does no real mutual exclusion is provided.  That 
  implementation is suitable for use in single-threaded applications
  or applications that only use SQLite in a single thread.  Other
  real mutex implementations are provided based on the underlying
  operating system.
}

PARAGRAPH {
  Embedded applications may wish to provide their own mutex implementation.
  If SQLite is compiled with the -DSQLITE_MUTEX_APPDEF=1 compile-time flag
  then the SQLite core provides no mutex subsystem and a mutex subsystem
  that matches the interface described above must be provided by the
  application that links against SQLite.
}

HEADING 1 {Other Interface Changes}

PARAGRAPH {
  Version 3.5.0 of SQLite changes the behavior of a few APIs in ways
  that are technically incompatible.  However, these APIs are seldom
  used and even when they are used it is difficult to imagine a
  scenario where the change might break something.  The changes
  actually makes these interface much more useful and powerful.
}

PARAGRAPH {
  Prior to version 3.5.0, the [sqlite3_enable_shared_cache()] API
  would enable and disable the shared cache feature for all connections
  within a single thread - the same thread from which the 
  sqlite3_enable_shared_cache() routine was called.  Database connections
  that used the shared cache were restricted to running in the same
  thread in which they were opened.  Beginning with version 3.5.0,
  the sqlite3_enable_shared_cache() applies to all database connections
  in all threads within the process.  Now database connections running
  in separate threads can share a cache.  And database connections that
  use shared cache can migrate from one thread to another.
}

PARAGRAPH {
  Prior to version 3.5.0 the [sqlite3_soft_heap_limit()] set an upper
  bound on heap memory usage for all database connections within a
  single thread.  Each thread could have its own heap limit.  Beginning
  in version 3.5.0, there is a single heap limit for the entire process.
  This seems more restrictive (one limit as opposed to many) but in
  practice it is what most users want.
}

PARAGRAPH {
  Prior to version 3.5.0 the [sqlite3_release_memory()] function would
  try to reclaim memory from all database connections in the same thread
  as the sqlite3_release_memory() call.  Beginning with version 3.5.0,
  the sqlite3_release_memory() function will attempt to reclaim memory
  from all database connections in all threads.
}

HEADING 1 {Summary}

PARAGRAPH {
  The transition from SQLite version 3.4.2 to 3.5.0 is a major change.
  Every source code file in the SQLite core had to be modified, some
  extensively.  And the change introduced some minor incompatibilities
  in the C interface.  But we feel that the benefits of the transition
  from 3.4.2 to 3.5.0 far outweigh the pain of porting.  The new
  VFS layer is now well-defined and stable and should simplify future
  customizations.  The VFS layer, and the separable memory allocator
  and mutex subsystems allow a standard SQLite source code amalgamation
  to be used in an embedded project without change, greatly simplifying
  configuration management.  And the resulting system is much more
  tolerant of highly threaded designs.
}