Documentation Source Text

Check-in [a1807b9496]
Login

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

Overview
Comment:Updates to system requirements.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: a1807b9496f5cdd9a14408dfea27484a6b486378
User & Date: drh 2008-07-23 15:38:16
Context
2008-07-28
15:01
Start enumerating the assumptions sqlite makes related to the state of the file system following a power failure or OS crash. check-in: ac2c5476d0 user: dan tags: trunk
2008-07-23
15:38
Updates to system requirements. check-in: a1807b9496 user: drh tags: trunk
2008-07-22
18:55
Modify fileio.in to add requirements to the database as it is parsed. check-in: a9b591daa0 user: dan tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/capi3ref.in.

17
18
19
20
21
22
23
24
25
26
27



28
29
30
31
32
33
34
..
57
58
59
60
61
62
63


64
65
66
67
68
69
70
set rowbody {}     ;# Content of a row
set rowtag {}      ;# 
unset -nocomplain keyword

# End a table row or the complete table.
#
proc endrow {} {
  global inrow body rowbody rowtag keyword
  if {$inrow} {
    set rowbody [string trim $rowbody]
    append body $rowbody</td></tr>\n



    hd_requirement $rowtag $rowbody
    set keyword($rowtag) 1
    set inrow 0
    set rowbody {}
    set rowtag {}
  }
}
................................................................................
  if {$phase==0} {
    # Looking for the CAPI3REF: keyword.  This marks the beginning of
    # an interface definition.  When the CAPI3REF keywords is seen, 
    # record the interface title and then switch to "phase 1".
    #
    if {[regexp {^\*\* CAPI3REF: +(.*)} $line all tx]} {
      set title $tx


      set title_lineno $lineno
      set phase 1
    }
  } elseif {$phase==1} {
    if {[string range $line 0 1]=="**"} {
      # Record all lines of column following the CAPI3REF keyword as the
      # description of the interface.  Except, look for special keywords







|



>
>
>







 







>
>







17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
..
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
set rowbody {}     ;# Content of a row
set rowtag {}      ;# 
unset -nocomplain keyword

# End a table row or the complete table.
#
proc endrow {} {
  global inrow body rowbody rowtag keyword dflt_parent
  if {$inrow} {
    set rowbody [string trim $rowbody]
    append body $rowbody</td></tr>\n
    if {$dflt_parent!=""} {
      append rowbody " <$dflt_parent>"
    }
    hd_requirement $rowtag $rowbody
    set keyword($rowtag) 1
    set inrow 0
    set rowbody {}
    set rowtag {}
  }
}
................................................................................
  if {$phase==0} {
    # Looking for the CAPI3REF: keyword.  This marks the beginning of
    # an interface definition.  When the CAPI3REF keywords is seen, 
    # record the interface title and then switch to "phase 1".
    #
    if {[regexp {^\*\* CAPI3REF: +(.*)} $line all tx]} {
      set title $tx
      set dflt_parent {}
      regexp {<([AHLS]\d\d\d\d\d)>} $title all dflt_parent
      set title_lineno $lineno
      set phase 1
    }
  } elseif {$phase==1} {
    if {[string range $line 0 1]=="**"} {
      # Record all lines of column following the CAPI3REF keyword as the
      # description of the interface.  Except, look for special keywords

Changes to pages/sysreq.in.

147
148
149
150
151
152
153








154
155
156
157
158
159
160
...
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
...
484
485
486
487
488
489
490









491
492
493
494
495
496
497
...
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
...
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
...
576
577
578
579
580
581
582















583
584
585
586
587
588
589
...
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
  information can be transfered from from one database to another 
  atomically, or so that queries can join data across multiple
  databases.
} {  
  The SQLite library shall support simultaneous access to multiple
  database files on the same database connection.
}









</tcl>
<h2>2.0 SQLite is designed to be extensible by the application</h2>
<tcl>

sysreq S20000 {} {
  SQLite is intended to be an embedded database that functions well
................................................................................
  SQLite works on common workstations and in embedded systems.
  Sometimes these devices, particularly embedded systems,
  have odd and unusual operating systems.  In order to support
  this level of portability, SQLite allows the interface to the operating
  system to be defined at run-time.
} {
  The SQLite library shall provide interfaces that permit the application
  to override operating-system interfaces.
}
sysreq S20110 S20100 {} {
  The SQLite library shall provide interfaces that permit the application
  to override the interfaces used to read and write persistent storage.
}
sysreq S20120 S20100 {} {
  The SQLite library shall provide interfaces that permit the application
................................................................................
  The SQLite library shall automatically control access to common
  databases from different connections in different threads or processes.
}
sysreq S40400 S40000 {} {
  The SQLite library shall notify the application if an operation can
  not be completed due to concurrent access constraints.
}










</tcl>
<h2>5.0 SQLite is cross-platform</h2>
<tcl>

sysreq S50000 {} {
  Cross-platform in this context means that the SQLite 
................................................................................
  different size integers, and different byte orders.  The same
  database file should work on any machine.
} {
  SQLite database files shall by processor and byte-order independent.
}

</tcl>
<h2>6.0 Other Features</h2>
<tcl>

sysreq S60000 {} {
  Some applications need to be able to discover characteristics of
  their environment at run-time and to make appropriate adjustments to
  their processing to accommodate the environment they find themselves in.
  SQLite attempts to support this need.
................................................................................

sysreq S60200 S60000 {
  In addition to the compile-time characteristics, SQLite allows
  the run-time settings of the library and of the underlying
  database file to be interrogated.
} {
  The SQLite library shall provide interfaces that an application can
  use to find run-time performance characteristics of the
  SQLite library.
}
sysreq S60300 S60000 {} {
  The SQLite library shall provide interfaces that permit an application
  to query the schema of a database.
}
sysreq S60400 S60000 {} {
................................................................................
  to monitor sequence of queries and progress of submitted to SQLite.
}
sysreq S60500 S60000 {} {
  The SQLite library shall provide interfaces that allow an application
  to discover the algorithms that SQLite has chosen to implement specific
  SQL statements.
}
















sysreq S70000 {} {
  Many applications need to be able to safely process data or
  even SQL statements that are received from untrusted sources.
  An "SQL Injection Attack" occurs when an adversary intentionally
  introduces data that is designed to have undesirable side effects
  on the database files.  For example, suppose an application generates
................................................................................
  SQLite supports interfaces that allow the CLI and similar applications
  to know if the input it has gathered so far is complete or if it needs
  to await additional input before processing the SQL.
} {
  The SQLite library shall provide interfaces that test to see if an
  SQL statement being received incrementally is complete.
}













</tcl>
<h2>7.0 Summary Of System Requirements</h2>

<p>The foregoing contained both system requirements and explanatory
text interspersed.  The following is a reproduction of the system
requirements without the explanatory text, as a convenient reference.
The top-level system requirements are shown first, followed by lower-level
system requirements that provide additional detail.</p>

<h3>7.1 Top-level System Requirements</h3>

<tcl>
foreach {id derivedfrom text} $sysreq_list {
  if {[llength $derivedfrom]>0} continue
  hd_puts "<blockquote><b>$id:</b>"
  hd_resolve $text
  hd_puts </blockquote>
}
</tcl>

<h3>7.2 Derived System Requirements</h3>

<tcl>
foreach {id derivedfrom text} $sysreq_list {
  if {[llength $derivedfrom]==0} continue
  hd_puts "<blockquote><b>$id:</b>"
  hd_resolve $text
  hd_puts </blockquote>
}
</tcl>







>
>
>
>
>
>
>
>







 







|







 







>
>
>
>
>
>
>
>
>







 







|







 







|







 







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







 








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

|







|










|









147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
...
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
...
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
...
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
...
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
...
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
...
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
  information can be transfered from from one database to another 
  atomically, or so that queries can join data across multiple
  databases.
} {  
  The SQLite library shall support simultaneous access to multiple
  database files on the same database connection.
}

sysreq S10700 S10000 {
  A database is of little practical use if one is unable to obtain
  information from the database.  Hence:
} {
  The SQLite library shall provide interfaces that allow the application
  to obtain the status and results of SQL operations.
}

</tcl>
<h2>2.0 SQLite is designed to be extensible by the application</h2>
<tcl>

sysreq S20000 {} {
  SQLite is intended to be an embedded database that functions well
................................................................................
  SQLite works on common workstations and in embedded systems.
  Sometimes these devices, particularly embedded systems,
  have odd and unusual operating systems.  In order to support
  this level of portability, SQLite allows the interface to the operating
  system to be defined at run-time.
} {
  The SQLite library shall provide interfaces that permit the application
  to override interfaces to the platform on which the application is running.
}
sysreq S20110 S20100 {} {
  The SQLite library shall provide interfaces that permit the application
  to override the interfaces used to read and write persistent storage.
}
sysreq S20120 S20100 {} {
  The SQLite library shall provide interfaces that permit the application
................................................................................
  The SQLite library shall automatically control access to common
  databases from different connections in different threads or processes.
}
sysreq S40400 S40000 {} {
  The SQLite library shall notify the application if an operation can
  not be completed due to concurrent access constraints.
}
sysreq S40410 S40000 {
  If an SQL statement cannot be completed because another process is
  holding a lock on the database, then the application needs to be able
  to take corrective action, such waiting for the lock to clear.
} {
  The SQLite library shall provide interfaces to assist the application
  in responding appropriately when an operation can
  not be completed due to concurrent access constraints.
}

</tcl>
<h2>5.0 SQLite is cross-platform</h2>
<tcl>

sysreq S50000 {} {
  Cross-platform in this context means that the SQLite 
................................................................................
  different size integers, and different byte orders.  The same
  database file should work on any machine.
} {
  SQLite database files shall by processor and byte-order independent.
}

</tcl>
<h2>6.0 Introspection</h2>
<tcl>

sysreq S60000 {} {
  Some applications need to be able to discover characteristics of
  their environment at run-time and to make appropriate adjustments to
  their processing to accommodate the environment they find themselves in.
  SQLite attempts to support this need.
................................................................................

sysreq S60200 S60000 {
  In addition to the compile-time characteristics, SQLite allows
  the run-time settings of the library and of the underlying
  database file to be interrogated.
} {
  The SQLite library shall provide interfaces that an application can
  use to find run-time performance characteristics and status of the
  SQLite library.
}
sysreq S60300 S60000 {} {
  The SQLite library shall provide interfaces that permit an application
  to query the schema of a database.
}
sysreq S60400 S60000 {} {
................................................................................
  to monitor sequence of queries and progress of submitted to SQLite.
}
sysreq S60500 S60000 {} {
  The SQLite library shall provide interfaces that allow an application
  to discover the algorithms that SQLite has chosen to implement specific
  SQL statements.
}

sysreq S60600 {S60000 S20200} {
  SQLite objects are often related.  For example, every prepared
  statement is associated with a database connection.  And every
  function context is associated with a prepared statement.  
  Applications and extensions frequently find it useful to be able
  to discover these relationships at runtime.  Hence:
} {
  The SQLite library shall provide interfaces that allow an application
  to discover relationships between SQLite objects.
}

</tcl>
<h2>7.0 Features to promote safe and robust application coding practices</h2>
<tcl>

sysreq S70000 {} {
  Many applications need to be able to safely process data or
  even SQL statements that are received from untrusted sources.
  An "SQL Injection Attack" occurs when an adversary intentionally
  introduces data that is designed to have undesirable side effects
  on the database files.  For example, suppose an application generates
................................................................................
  SQLite supports interfaces that allow the CLI and similar applications
  to know if the input it has gathered so far is complete or if it needs
  to await additional input before processing the SQL.
} {
  The SQLite library shall provide interfaces that test to see if an
  SQL statement being received incrementally is complete.
}

sysreq S70300 {S70000 S30000} {
  The concept of a "prepared statement" allows an SQL statement to be
  parsed and compiled once and then reused many times.  This is a performance
  advantage in many applications.  In addition, binding values to variables
  in the prepared statement is safer than embedding values as literals because
  bound values do not need to be quoted in order to avoid an SQL injection
  attack.
} {
  The SQLite library shall support prepared statement objects with
  late parameter binding
}

</tcl>
<h2>8.0 Summary Of System Requirements</h2>

<p>The foregoing contained both system requirements and explanatory
text interspersed.  The following is a reproduction of the system
requirements without the explanatory text, as a convenient reference.
The top-level system requirements are shown first, followed by lower-level
system requirements that provide additional detail.</p>

<h3>8.1 Top-level System Requirements</h3>

<tcl>
foreach {id derivedfrom text} $sysreq_list {
  if {[llength $derivedfrom]>0} continue
  hd_puts "<blockquote><b>$id:</b>"
  hd_resolve $text
  hd_puts </blockquote>
}
</tcl>

<h3>8.2 Derived System Requirements</h3>

<tcl>
foreach {id derivedfrom text} $sysreq_list {
  if {[llength $derivedfrom]==0} continue
  hd_puts "<blockquote><b>$id:</b>"
  hd_resolve $text
  hd_puts </blockquote>
}
</tcl>