Documentation Source Text

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

Changes to pages/testing.in.

   127    127   <li> Fuzz tests
   128    128   <li> Boundary value tests
   129    129   <li> Disabled optimization tests
   130    130   <li> Regression tests
   131    131   <li> Malformed database tests
   132    132   <li> Extensive use of assert() and run-time checks
   133    133   <li> Valgrind analysis
   134         -<li> Signed-integer overflow checks
          134  +<li> Undefined behavior checks
   135    135   <li> Checklists
   136    136   </ul>
   137    137   
   138    138   <tcl>hd_fragment {harnesses} {test harness} {three test harnesses}</tcl>
   139    139   <h2>2.0 Test Harnesses</h2>
   140    140   
   141    141   <p>There are three independent test harnesses used for testing the 
................................................................................
   720    720   If any discrepancies are found, an assertion fault is raised.</p>
   721    721   
   722    722   <p>The journal tests are an additional double-check over and above
   723    723   the crash tests to make sure that SQLite transactions will be atomic
   724    724   across system crashes and power failures.</p>
   725    725   
   726    726   <tcl>hd_fragment intoverflow</tcl>
   727         -<h3>8.6 Signed-Integer Overflow Checks</h3>
   728         -
   729         -<p>The various C language standards say that the signed-integer overflow
   730         -behavior is undefined.  In other words, when you add a value to a signed
   731         -integer such that the result is too large to fit in that integer, the
   732         -value does not necessarily wrap around to a negative number, as most
   733         -programmers expect.  It might do that.  But it might do something completely
   734         -different.  See, for example,
   735         -<a href="http://thiemonagel.de/2010/01/signed-integer-overflow/">here</a>
   736         -and <a href="http://blog.regehr.org/archives/482">here</a>.  Even the
   737         -same compiler might do something different with signed integer overflow
   738         -in different places in the code or at different optimizations settings.</p>
   739         -
   740         -<p>SQLite never overflows a signed integer.
   741         -To verify this, the test suites are run at least once when compiled with
   742         -the -ftrapv option to GCC.  The -ftrapv option causes GCC to generate code
   743         -that will panic() on a signed integer overflow.  In addition, there are
   744         -many test cases the strive to provoke integer overflows
   745         -using boundary value calculations such as
   746         - "<b>SELECT -1*(-9223372036854775808);</b>".
   747         -
          727  +<h3>8.6 Undefined Behavior Checks</h3>
          728  +
          729  +<p>In in the C programming language, it is very easy to write code that
          730  +has "undefined" or "implementation defined" behavior.
          731  +That means that the code might work during development, but then give
          732  +a different answer on a different system, or when recompiled using different
          733  +compiler options.  
          734  +Examples of undefined and implementation-defined behavior in
          735  +ANSI C include:
          736  +<ul>
          737  +<li>Signed integer overflow.  (Signed integer overflow does <u>not</u>
          738  +necessarily wrap around, as most people expect.)
          739  +<li>Shifting an N-bit integer by more than N bits.
          740  +<li>Shifting by a negative amount.
          741  +<li>Shifting a negative number.
          742  +<li>Using the memcpy() function on overlapping buffers.
          743  +<li>The order of evaluation of function arguments.
          744  +<li>Whether or not "char" variables are signed or unsigned.
          745  +<li>And so forth....
          746  +</ul>
          747  +
          748  +<p>Since undefined and implementation-defined behavior is non-portable
          749  +and can easily lead to incorrect answers, SQLite works very hard to avoid it.
          750  +For example,
          751  +when adding two integer column values together as part of an SQL statement,
          752  +SQLite does not simple add them together using the C-language "+" operator.
          753  +Instead, it first checks to make sure the
          754  +addition will not overflow, and if it will, it does the addition using
          755  +floating point instead.
          756  +
          757  +<p>To help ensure that SQLite does not make use of undefined or
          758  +implementation defined behavior, the test suites are rerun using
          759  +instrumented builds that try to detect undefined behavior.  For example,
          760  +test suites are run using the "-ftrapv" option of GCC.  And they
          761  +are run again using the "-fsanitize=undefined" option on Clang.  And
          762  +again using the "/RTC1" option in MSVC.  Then the test suites are rerun
          763  +using options like "-funsigned-char" and "-fsigned-char" to make sure
          764  +that implementation differences do not matter either.  Tests are then repeated
          765  +on 32-bit and 64-bit systems and on big-endian and little-endian systems,
          766  +using a variety of CPU architectures.
          767  +Furthermore, the test suites are augmented with many test cases that are
          768  +deliberately designed to provoke undefined behavior.  For example:
          769  +"<b>SELECT -1*(-9223372036854775808);</b>".
   748    770   
   749    771   <tcl>hd_fragment disopttest</tcl>
   750    772   <h2>9.0 Disabled Optimization Tests</h2>
   751    773   
   752    774   <p>The [sqlite3_test_control]([SQLITE_TESTCTRL_OPTIMIZATIONS], ...) interface
   753    775   allows selected SQL statement optimizations to be disabled at run-time.
   754    776   SQLite should always generate exactly the same answer with optimizations