SQLite源码剖析

/******************************************************************************

** This file is an amalgamation of many separate C source files from SQLite

** version 3.6.23.1.  By combining all the individual C code files into this

** single large file, the entire code can be compiled as a one translation

** unit.  This allows many compilers to do optimizations that would not be

** possible if the files were compiled separately.  Performance improvements

** of 5% are more are commonly seen when SQLite is compiled as a single

** translation unit.

**

** This file is all you need to compile SQLite.  To use SQLite in other

** programs, you need this file and the "sqlite3.h" header file that defines

** the programming interface to the SQLite library.  (If you do not have

** the "sqlite3.h" header file at hand, you will find a copy embedded within

** the text of this file.  Search for "Begin file sqlite3.h" to find the start

** of the embedded sqlite3.h header file.) Additional code files may be needed

** if you want a wrapper to interface SQLite with your choice of programming

** language. The code for the "sqlite3" command-line shell is also in a

** separate file. This file contains only code for the core SQLite library.

*/

//主程序定义SQLITE核心：define SQLITE_CORE 1

//主程序定义SQLITE_API。

//主程序序版本为合并后的源代码：define SQLITE_AMALGAMATION 1

#define SQLITE_CORE 1

#define SQLITE_AMALGAMATION 1

#ifndef SQLITE_PRIVATE

# define SQLITE_PRIVATE static

#endif

#ifndef SQLITE_API

# define SQLITE_API

#endif

/************** Begin file sqliteInt.h ***************************************/

/*

** 2001 September 15

**

** The author disclaims copyright to this source code.  In place of

** a legal notice, here is a blessing:

**

**    May you do good and not evil.

**    May you find forgiveness for yourself and forgive others.

**    May you share freely, never taking more than you give.

**

*************************************************************************

** Internal interface definitions for SQLite.

**

*/

//SQLITE内部接口定义

#ifndef _SQLITEINT_H_

#define _SQLITEINT_H_

//如果基础操作系统支持，可用#define开启大于2G的单个文件支持。

/*

** These #defines should enable >2GB file support on POSIX if the

** underlying operating system supports it.  If the OS lacks

** large file support, or if the OS is windows, these should be no-ops.

**_LARGEFILE_SOURCE宏必须在任何#include前使用

** Ticket #2739:  The _LARGEFILE_SOURCE macro must appear before any

** system #includes.  Hence, this block of code must be the very first

** code in all source files.

**在编译命令行使用-DSQLITE_DISABLE_LFS可禁止大文件支持，

** Large file support can be disabled using the -DSQLITE_DISABLE_LFS switch

** on the compiler command line.  This is necessary if you are compiling

** on a recent machine (ex: Red Hat 7.2) but you want your code to work

** on an older machine (ex: Red Hat 6.0).  If you compile on Red Hat 7.2

** without this option, LFS is enable.  But LFS does not exist in the kernel

** in Red Hat 6.0, so the code won't work.  Hence, for maximum binary

** portability you should omit LFS.

**

** Similar is true for Mac OS X.  LFS is only supported on Mac OS X 9 and later.

*/

//如果没禁止大文件支持，则定义相关常量

#ifndef SQLITE_DISABLE_LFS

# define _LARGE_FILE       1

# ifndef _FILE_OFFSET_BITS

#   define _FILE_OFFSET_BITS 64

# endif

# define _LARGEFILE_SOURCE 1

#endif

 

/*

** Include the configuration header output by 'configure' if we're using the

** autoconf-based build

*/

//如果使用autoconf-based构建，则include "config.h"

#ifdef _HAVE_SQLITE_CONFIG_H

#include "config.h"

#endif

 

/************** Include sqliteLimit.h in the middle of sqliteInt.h ***********/

/************** Begin file sqliteLimit.h *************************************/

/*

** 2007 May 7

**

** The author disclaims copyright to this source code.  In place of

** a legal notice, here is a blessing:

**

**    May you do good and not evil.

**    May you find forgiveness for yourself and forgive others.

**    May you share freely, never taking more than you give.

**

*************************************************************************

**

** This file defines various limits of what SQLite can process.

*/

 

/*

** The maximum length of a TEXT or BLOB in bytes.   This also

** limits the size of a row in a table or index.

**

** The hard limit is the ability of a 32-bit signed integer

** to count the size: 2^31-1 or 2147483647.

*/

//最大32位有符号整数

#ifndef SQLITE_MAX_LENGTH

# define SQLITE_MAX_LENGTH 1000000000

#endif

 

/*

** This is the maximum number of

**以下这些项的最大值:

**表中的列、索引中的列、视图的列、update的set从句的数量、select

**返回的字段数、GROUP BY 和ORDER BY的字段数、INSERT的values从句

**    * Columns in a table

**    * Columns in an index

**    * Columns in a view

**    * Terms in the SET clause of an UPDATE statement

**    * Terms in the result set of a SELECT statement

**    * Terms in the GROUP BY or ORDER BY clauses of a SELECT statement.

**    * Terms in the VALUES clause of an INSERT statement

**

** The hard upper limit here is 32676.  Most database people will

** tell you that in a well-normalized database, you usually should

** not have more than a dozen or so columns in any table.  And if

** that is the case, there is no point in having more than a few

** dozen values in any of the other situations described above.

*/

/*

**以下这些项的最大值:

**表中的列、索引中的列、视图的列、update的set从句的数量、select

**返回的字段数、GROUP BY 和ORDER BY的字段数、INSERT的values从句

*/

#ifndef SQLITE_MAX_COLUMN

# define SQLITE_MAX_COLUMN 2000

#endif

 

/*

** The maximum length of a single SQL statement in bytes.

**

** It used to be the case that setting this value to zero would

** turn the limit off.  That is no longer true.  It is not possible

** to turn this limit off.

*/

//SQL语句的最大长度

#ifndef SQLITE_MAX_SQL_LENGTH

# define SQLITE_MAX_SQL_LENGTH 1000000000

#endif

 

/*

** The maximum depth of an expression tree. This is limited to

** some extent by SQLITE_MAX_SQL_LENGTH. But sometime you might

** want to place more severe limits on the complexity of an

** expression.

**

** A value of 0 used to mean that the limit was not enforced.

** But that is no longer true.  The limit is now strictly enforced

** at all times.

*/

//解释树的最大深度

#ifndef SQLITE_MAX_EXPR_DEPTH

# define SQLITE_MAX_EXPR_DEPTH 1000

#endif

 

/*

** The maximum number of terms in a compound SELECT statement.

** The code generator for compound SELECT statements does one

** level of recursion for each term.  A stack overflow can result

** if the number of terms is too large.  In practice, most SQL

** never has more than 3 or 4 terms.  Use a value of 0 to disable

** any limit on the number of terms in a compount SELECT.

*/

//复合SQL语句的最大项数

#ifndef SQLITE_MAX_COMPOUND_SELECT

# define SQLITE_MAX_COMPOUND_SELECT 500

#endif

/*

** The maximum number of opcodes in a VDBE program.

** Not currently enforced.

*/

//VDBE程序的最大操作码数目

#ifndef SQLITE_MAX_VDBE_OP

# define SQLITE_MAX_VDBE_OP 25000

#endif

 

/*

** The maximum number of arguments to an SQL function.

*/

//SQL函数的最大参数数目

#ifndef SQLITE_MAX_FUNCTION_ARG

# define SQLITE_MAX_FUNCTION_ARG 127

#endif

 

/*

** The maximum number of in-memory pages to use for the main database

** table and for temporary tables.  The SQLITE_DEFAULT_CACHE_SIZE

*/

//主数据库表和临时表的最大内存大小

#ifndef SQLITE_DEFAULT_CACHE_SIZE

# define SQLITE_DEFAULT_CACHE_SIZE  2000

#endif

#ifndef SQLITE_DEFAULT_TEMP_CACHE_SIZE

# define SQLITE_DEFAULT_TEMP_CACHE_SIZE  500

#endif

 

/*

** The maximum number of attached databases.  This must be between 0

** and 30.  The upper bound on 30 is because a 32-bit integer bitmap

** is used internally to track attached databases.

*/

//附加数据库的数目

#ifndef SQLITE_MAX_ATTACHED

# define SQLITE_MAX_ATTACHED 10

#endif

 

 

/*

** The maximum value of a ?nnn wildcard that the parser will accept.

*/

//解析器接受的匹配符参数最大值

#ifndef SQLITE_MAX_VARIABLE_NUMBER

# define SQLITE_MAX_VARIABLE_NUMBER 999

#endif

 

/* Maximum page size.  The upper bound on this value is 32768.  This a limit

** imposed by the necessity of storing the value in a 2-byte unsigned integer

** and the fact that the page size must be a power of 2.

**

** If this limit is changed, then the compiled library is technically

** incompatible with an SQLite library compiled with a different limit. If

** a process operating on a database with a page-size of 65536 bytes

** crashes, then an instance of SQLite compiled with the default page-size

** limit will not be able to rollback the aborted transaction. This could

** lead to database corruption.

*/

//最大页面大小

#ifndef SQLITE_MAX_PAGE_SIZE

# define SQLITE_MAX_PAGE_SIZE 32768

#endif

 

 

/*

** The default size of a database page.

*/

//数据库页面的默认大小

#ifndef SQLITE_DEFAULT_PAGE_SIZE

# define SQLITE_DEFAULT_PAGE_SIZE 1024

#endif

#if SQLITE_DEFAULT_PAGE_SIZE>SQLITE_MAX_PAGE_SIZE

# undef SQLITE_DEFAULT_PAGE_SIZE

# define SQLITE_DEFAULT_PAGE_SIZE SQLITE_MAX_PAGE_SIZE

#endif

 

/*

** Ordinarily, if no value is explicitly provided, SQLite creates databases

** with page size SQLITE_DEFAULT_PAGE_SIZE. However, based on certain

** device characteristics (sector-size and atomic write() support),

** SQLite may choose a larger value. This constant is the maximum value

** SQLite will choose on its own.

*/

//数据库页面的最大默认大小

#ifndef SQLITE_MAX_DEFAULT_PAGE_SIZE

# define SQLITE_MAX_DEFAULT_PAGE_SIZE 8192

#endif

#if SQLITE_MAX_DEFAULT_PAGE_SIZE>SQLITE_MAX_PAGE_SIZE

# undef SQLITE_MAX_DEFAULT_PAGE_SIZE

# define SQLITE_MAX_DEFAULT_PAGE_SIZE SQLITE_MAX_PAGE_SIZE

#endif

 

 

/*

** Maximum number of pages in one database file.

**

** This is really just the default value for the max_page_count pragma.

** This value can be lowered (or raised) at run-time using that the

** max_page_count macro.

*/

//单个数据库文件的最大页数数

#ifndef SQLITE_MAX_PAGE_COUNT

# define SQLITE_MAX_PAGE_COUNT 1073741823

#endif

 

/*

** Maximum length (in bytes) of the pattern in a LIKE or GLOB

** operator.

*/

// LIKE or GLOB模式的最大长度（字节）

#ifndef SQLITE_MAX_LIKE_PATTERN_LENGTH

# define SQLITE_MAX_LIKE_PATTERN_LENGTH 50000

#endif

 

/*

** Maximum depth of recursion for triggers.

**

** A value of 1 means that a trigger program will not be able to itself

** fire any triggers. A value of 0 means that no trigger programs at all

** may be executed.

*/

//触发器程序的递归深度

#ifndef SQLITE_MAX_TRIGGER_DEPTH

# define SQLITE_MAX_TRIGGER_DEPTH 1000

#endif

//SQLITE限制参数定义完毕

/************** End of sqliteLimit.h *****************************************/

/************** Continuing where we left off in sqliteInt.h ******************/

//禁止Borland编译器的讨厌的警告

/* Disable nuisance warnings on Borland compilers */

#if defined(__BORLANDC__)

#pragma warn -rch /* unreachable code */

#pragma warn -ccc /* Condition is always true or false */

#pragma warn -aus /* Assigned value is never used */

#pragma warn -csu /* Comparing signed and unsigned */

#pragma warn -spa /* Suspicious pointer arithmetic */

#endif

//定义为GNU源码

/* Needed for various definitions... */

#ifndef _GNU_SOURCE

# define _GNU_SOURCE

#endif

 

/*

** Include standard header files as necessary

*/

//包含必要的头文件

#ifdef HAVE_STDINT_H

#include <stdint.h>

#endif

#ifdef HAVE_INTTYPES_H

#include <inttypes.h>

#endif

 

/*

** The number of samples of an index that SQLite takes in order to

** construct a histogram of the table content when running ANALYZE

** and with SQLITE_ENABLE_STAT2

*/

//索引样本数

#define SQLITE_INDEX_SAMPLES 10

 

/*

** The following macros are used to cast pointers to integers and

** integers to pointers.  The way you do this varies from one compiler

** to the next, so we have developed the following set of #if statements

** to generate appropriate macros for a wide range of compilers.

**

** The correct "ANSI" way to do this is to use the intptr_t type.

** Unfortunately, that typedef is not available on all compilers, or

** if it is available, it requires an #include of specific headers

** that very from one machine to the next.

**

** Ticket #3860:  The llvm-gcc-4.2 compiler from Apple chokes on

** the ((void*)&((char*)0)[X]) construct.  But MSVC chokes on ((void*)(X)).

** So we have to define the macros in different ways depending on the

** compiler.

*/

//下列宏完成指针转整数和整数转指针

#if defined(__PTRDIFF_TYPE__)  /* This case should work for GCC */

# define SQLITE_INT_TO_PTR(X)  ((void*)(__PTRDIFF_TYPE__)(X))

# define SQLITE_PTR_TO_INT(X)  ((int)(__PTRDIFF_TYPE__)(X))

#elif !defined(__GNUC__)       /* Works for compilers other than LLVM */

# define SQLITE_INT_TO_PTR(X)  ((void*)&((char*)0)[X])

# define SQLITE_PTR_TO_INT(X)  ((int)(((char*)X)-(char*)0))

#elif defined(HAVE_STDINT_H)   /* Use this case if we have ANSI headers */

# define SQLITE_INT_TO_PTR(X)  ((void*)(intptr_t)(X))

# define SQLITE_PTR_TO_INT(X)  ((int)(intptr_t)(X))

#else                          /* Generates a warning - but it always works */

# define SQLITE_INT_TO_PTR(X)  ((void*)(X))

# define SQLITE_PTR_TO_INT(X)  ((int)(X))

#endif

 

/*

** The SQLITE_THREADSAFE macro must be defined as either 0 or 1.

** Older versions of SQLite used an optional THREADSAFE macro.

** We support that for legacy

*/

// SQLITE_THREADSAFE线程安全宏被定义为0或1,

#if !defined(SQLITE_THREADSAFE)

#if defined(THREADSAFE)

# define SQLITE_THREADSAFE THREADSAFE

#else

# define SQLITE_THREADSAFE 1

#endif

#endif

 

/*

** The SQLITE_DEFAULT_MEMSTATUS macro must be defined as either 0 or 1.

** It determines whether or not the features related to

** SQLITE_CONFIG_MEMSTATUS are available by default or not. This value can

** be overridden at runtime using the sqlite3_config() API.

*/

// SQLITE_DEFAULT_MEMSTATUS宏被定义为0或1，在运行时可使

//用sqlite3_config() API修改该值

#if !defined(SQLITE_DEFAULT_MEMSTATUS)

# define SQLITE_DEFAULT_MEMSTATUS 1

#endif

    /* 
     
    ** The SQLITE_DEFAULT_MEMSTATUS macro must be defined as either 0 or 1. 
     
    ** It determines whether or not the features related to  
     
    ** SQLITE_CONFIG_MEMSTATUS are available by default or not. This value can 
     
    ** be overridden at runtime using the sqlite3_config() API. 
     
    */  
      
    // SQLITE_DEFAULT_MEMSTATUS宏被定义为0或1，在运行时可使  
      
    //用sqlite3_config() API修改该值  
      
    #if !defined(SQLITE_DEFAULT_MEMSTATUS)  
      
    # define SQLITE_DEFAULT_MEMSTATUS 1  
      
    #endif  
      
       
      
    /* 
     
    ** Exactly one of the following macros must be defined in order to 
     
    ** specify which memory allocation subsystem to use. 
     
    **该宏不一定要被定义，使用SQLITE_SYSTEM_MALLOC标准内存分配系统malloc()还是malloc()的SQLITE_MEMDEBUG调试版本 
     
    **     SQLITE_SYSTEM_MALLOC          // Use normal system malloc() 
     
    **     SQLITE_MEMDEBUG               // Debugging version of system malloc() 
     
    ** 
     
    ** (Historical note:  There used to be several other options, but we've 
     
    ** pared it down to just these two.) 
     
    ** 
     
    ** If none of the above are defined, then set SQLITE_SYSTEM_MALLOC as 
     
    ** the default. 
     
    */  
      
    //SQLITE_SYSTEM_MALLOC和SQLITE_MEMDEBUG不能同时被定义  
      
    #if defined(SQLITE_SYSTEM_MALLOC)+defined(SQLITE_MEMDEBUG)>1  
      
    # error "At most one of the following compile-time configuration options  
      
     is allows: SQLITE_SYSTEM_MALLOC, SQLITE_MEMDEBUG"  
      
    #endif  
      
    //默认使用SQLITE_SYSTEM_MALLOC标准  
      
    #if defined(SQLITE_SYSTEM_MALLOC)+defined(SQLITE_MEMDEBUG)==0  
      
    # define SQLITE_SYSTEM_MALLOC 1  
      
    #endif  
      
       
      
    /* 
     
    ** If SQLITE_MALLOC_SOFT_LIMIT is not zero, then try to keep the 
     
    ** sizes of memory allocations below this value where possible. 
     
    */  
      
    // SQLITE_MALLOC_SOFT_LIMIT非0,则试图把分配的内存控制在这些值以内  
      
    #if !defined(SQLITE_MALLOC_SOFT_LIMIT)  
      
    # define SQLITE_MALLOC_SOFT_LIMIT 1024  
      
    #endif  
      
       
      
    /* 
     
    ** We need to define _XOPEN_SOURCE as follows in order to enable 
     
    ** recursive mutexes on most Unix systems.  But Mac OS X is different. 
     
    ** The _XOPEN_SOURCE define causes problems for Mac OS X we are told, 
     
    ** so it is omitted there.  See ticket #2673. 
     
    **， 
     
    ** Later we learn that _XOPEN_SOURCE is poorly or incorrectly 
     
    ** implemented on some systems.  So we avoid defining it at all 
     
    ** if it is already defined or if it is unneeded because we are 
     
    ** not doing a threadsafe build.  Ticket #2681. 
     
    ** 
     
    ** See also ticket #2741. 
     
    */  
      
    //在大多数UNIX系统中，我们需要定义_XOPEN_SOURCE允许递归互斥  
      
    //对于Mac OS X, _XOPEN_SOURCE导致一些问题发生  
      
    #if !defined(_XOPEN_SOURCE) && !defined(__DARWIN__) && !defined(__APPLE__) && SQLITE_THREADSAFE  
      
    #  define _XOPEN_SOURCE 500  /* Needed to enable pthread recursive mutexes */  
      
    #endif  
      
       
      
    /* 
     
    ** The TCL headers are only needed when compiling the TCL bindings. 
     
    **TCL(Tool   Command   Language)是一种解释执行的脚本语言。具有良好的跨平台特性和**可扩展性，TCL本身是用C语言实现的，可以很方便的通过C语言进行扩充，增加新的**命令，也可以很方便的把TCL解释器嵌入你的程序中。TCL解释器也是公开源代码的。 
     
    **当编译TCL绑定时，才需要TCL头文件 
     
    */  
      
    //如果需要绑定TCL，则包括tcl.h  
      
    #if defined(SQLITE_TCL) || defined(TCLSH)  
      
    # include <tcl.h>  
      
    #endif  

    /* 
     
    ** Many people are failing to set -DNDEBUG=1 when compiling SQLite. 
     
    ** Setting NDEBUG makes the code smaller and run faster.  So the following 
     
    ** lines are added to automatically set NDEBUG unless the -DSQLITE_DEBUG=1 
     
    ** option is set.  Thus NDEBUG becomes an opt-in rather than an opt-out 
     
    ** feature. 
     
    */  
      
    // NDEBUG设置能使代码更小，且运行地更快  
      
    #if !defined(NDEBUG) && !defined(SQLITE_DEBUG)   
      
    # define NDEBUG 1  
      
    #endif  
      
       
      
    /* 
     
    ** The testcase() macro is used to aid in coverage testing.  When  
     
    ** doing coverage testing, the condition inside the argument to 
     
    ** testcase() must be evaluated both true and false in order to 
     
    ** get full branch coverage.  The testcase() macro is inserted 
     
    ** to help ensure adequate test coverage in places where simple 
     
    ** condition/decision coverage is inadequate.  For example, testcase() 
     
    ** can be used to make sure boundary values are tested.  For 
     
    ** bitmask tests, testcase() can be used to make sure each bit 
     
    ** is significant and used at least once.  On switch statements 
     
    ** where multiple cases go to the same block of code, testcase() 
     
    ** can insure that all cases are evaluated. 
     
    ** 
     
    */  
      
    //在覆盖测试时使用testcase()宏  
      
    #ifdef SQLITE_COVERAGE_TEST  
      
    SQLITE_PRIVATE   void sqlite3Coverage(int);  
      
    # define testcase(X)  if( X ){ sqlite3Coverage(__LINE__); }  
      
    #else  
      
    # define testcase(X)  
      
    #endif  
      
       
      
    /* 
     
    ** The TESTONLY macro is used to enclose variable declarations or 
     
    ** other bits of code that are needed to support the arguments 
     
    ** within testcase() and assert() macros. 
     
    */  
      
    // TESTONLY将变量声明或需要使用testcase()和assert()宏  
      
    //的参数的代码片断包围  
      
    #if !defined(NDEBUG) || defined(SQLITE_COVERAGE_TEST)  
      
    # define TESTONLY(X)  X  
      
    #else  
      
    # define TESTONLY(X)  
      
    #endif  
      
       
      
    /* 
     
    ** Sometimes we need a small amount of code such as a variable initialization 
     
    ** to setup for a later assert() statement.  We do not want this code to 
     
    ** appear when assert() is disabled.  The following macro is therefore 
     
    ** used to contain that setup code.  The "VVA" acronym stands for 
     
    ** "Verification, Validation, and Accreditation".  In other words, the 
     
    ** code within VVA_ONLY() will only run during verification processes. 
     
    */  
      
    //在写一段代码如变量初始化时，需要设置assert()语句进行验证，  
      
    //当assert（）被禁止时，我们不希望看到这些代码  
      
    // 包括VVA_ONLY()的代码仅在验证后才运行  
      
    #ifndef NDEBUG  
      
    # define VVA_ONLY(X)  X  
      
    #else  
      
    # define VVA_ONLY(X)  
      
    #endif  
      
       
      
    /* 
     
    ** ALWAYS和NEVER宏环绕boolean表达式，分别为true或false， 
     
    **代码中的这些表达式能被完全忽略,但他们在少数情况下被用于提高SQLITE 
     
    **异常恢复能力，使代码自修复。 
     
    ** The ALWAYS and NEVER macros surround boolean expressions which  
     
    ** are intended to always be true or false, respectively.  Such 
     
    ** expressions could be omitted from the code completely.  But they 
     
    ** are included in a few cases in order to enhance the resilience 
     
    ** of SQLite to unexpected behavior - to make the code "self-healing" 
     
    ** or "ductile" rather than being "brittle" and crashing at the first 
     
    ** hint of unplanned behavior. 
     
    ** ALWAYS和NEVER可被用于防御代。当做覆盖测试时， 
     
    **ALWAYS和NEVER被硬编码为true和false， 
     
    **无法访问的代码，不能算作未经测试的代码。 
     
    ** In other words, ALWAYS and NEVER are added for defensive code. 
     
    ** 
     
    ** When doing coverage testing ALWAYS and NEVER are hard-coded to 
     
    ** be true and false so that the unreachable code then specify will 
     
    ** not be counted as untested code. 
     
    */  
      
    #if defined(SQLITE_COVERAGE_TEST)  
      
    # define ALWAYS(X)      (1)  
      
    # define NEVER(X)       (0)  
      
    #elif !defined(NDEBUG)  
      
    # define ALWAYS(X)      ((X)?1:(assert(0),0))  
      
    # define NEVER(X)       ((X)?(assert(0),1):0)  
      
    #else  
      
    # define ALWAYS(X)      (X)  
      
    # define NEVER(X)       (X)  
      
    #endif  
      
       
      
    /* 
     
    ** The macro unlikely() is a hint that surrounds a boolean 
     
    ** expression that is usually false.  Macro likely() surrounds 
     
    ** a boolean expression that is usually true.  GCC is able to 
     
    ** use these hints to generate better code, sometimes. 
     
    */  
      
    // 对于包围的boolean表达式，unlikely()为false,likely()为true  
      
    // GCC有时可使用这些暗示产生更好的代码。  
      
    #if defined(__GNUC__) && 0  
      
    # define likely(X)    __builtin_expect((X),1)  
      
    # define unlikely(X)  __builtin_expect((X),0)  
      
    #else  
      
    # define likely(X)    !!(X)  
      
    # define unlikely(X)  !!(X)  
      
    #endif  

    /************** Include sqlite3.h in the middle of sqliteInt.h ***************/  
      
    /************** Begin file sqlite3.h *****************************************/  
      
    //在sqliteInt.h中包含sqlite3.h  
      
    /* 
     
    ** 2001 September 15 
     
    ** 
     
    ** The author disclaims copyright to this source code.  In place of 
     
    ** a legal notice, here is a blessing: 
     
    ** 
     
    **    May you do good and not evil. 
     
    **    May you find forgiveness for yourself and forgive others. 
     
    **    May you share freely, never taking more than you give. 
     
    ** 
     
    *************************************************************************sqlite库的客户端接口，如果在这个文件中没有出现过某个C函数、 
     
    **结构、数据类型、或常量定义，那么它是不公开的SQLITE的API， 
     
    **不会声明随时有可能改变，也不能做为使用SQLITE开发的参考。 
     
    ** This header file defines the interface that the SQLite library 
     
    ** presents to client programs.  If a C-function, structure, datatype, 
     
    ** or constant definition does not appear in this file, then it is 
     
    ** not a published API of SQLite, is subject to change without 
     
    ** notice, and should not be referenced by programs that use SQLite. 
     
    **有些定义被标明experimental(实验性的)，这些接口不久会被加入SQLITE。 
     
    **虽然不希望改变实验性接口，会保留较小改变的权力，使用in the wild 
     
    **标明的地方要谨慎改变 
     
    ** Some of the definitions that are in this file are marked as 
     
    ** "experimental".  Experimental interfaces are normally new 
     
    ** features recently added to SQLite.  We do not anticipate changes 
     
    ** to experimental interfaces but reserve the right to make minor changes 
     
    ** if experience from use "in the wild" suggest such changes are prudent. 
     
    **SQLITE的官方C语言API文档从注解生成，这个文件在SQLITE接口 
     
    **操作方面具有权威 
     
    ** The official C-language API documentation for SQLite is derived 
     
    ** from comments in this file.  This file is the authoritative source 
     
    ** on how SQLite interfaces are suppose to operate. 
     
    ** 构造管理文件是sqlite.h.in，makefile对这个文件 
     
    **（比如嵌入式版本中）做较小改动，build过程中其名改为sqlite3.h 
     
    ** 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. 
     
    */  
      
    #ifndef _SQLITE3_H_  
      
    #define _SQLITE3_H_  
      
    #include <stdarg.h>       
      
    /*SQLITE接口需要va_list定义 Needed for the definition of va_list */  
      
       
      
    /* 
     
    ** Make sure we can call this stuff from C++. 
     
    */  
      
    // extern声明的函数和变量可以在本模块或其他模块中使用。  
      
    // extern "C"包含双重含义，其一：被它修饰的目标是“extern”的；  
      
    //其二：被它修饰的目标是“C”的。extern "C"仅被使用在C++调用C程  
      
    //序情况，C不能使用。#if 0把它屏蔽了，如果使用C++编译器，可以  
      
    //可以打开该选项  
      
    //比如test.cpp(C++源码文件)需要调用myc.h这个C头文件中  
      
    //用extern声明的函数，可以如下书写:  
      
    //extern "C"  
      
    //{  
      
    //#include "myc.h"  
      
    //}  
      
    #if 0  
      
    extern "C" {  
      
    #endif  
      
       
      
       
      
    /* 
     
    ** Add the ability to override 'extern' 
     
    */  
      
    //定义extern的宏，可使用SQLITE_EXTERN来完成extern功能  
      
    #ifndef SQLITE_EXTERN  
      
    # define SQLITE_EXTERN extern  
      
    #endif  
      
    //定义SQLITE_API宏  
      
    #ifndef SQLITE_API  
      
    # define SQLITE_API  
      
    #endif  

/*

** Add the ability to override 'extern'

*/

//定义extern的宏，可使用SQLITE_EXTERN来完成extern功能

#ifndef SQLITE_EXTERN

# define SQLITE_EXTERN extern

#endif

//定义SQLITE_API宏

#ifndef SQLITE_API

# define SQLITE_API

#endif

 

 

/* no-op宏经常在接口前标记那些实验性的和不推荐的接口。新应用程序最好

**不使用不推荐的接口，它们支持向后兼容。程序员必须意识到实验性接口

**会在某个版本中改变

** These no-op macros are used in front of interfaces to mark those

** interfaces as either deprecated or experimental.  New applications

** should not use deprecated interfaces - they are support for backwards

** compatibility only.  Application writers should be aware that

** experimental interfaces are subject to change in point releases.

**这些宏在他们需要时，能实现编译器魔法compiler magic警告信息，

**编译器魔法最终产生BUG报告，编译器会试着使用noop宏。

** These macros used to resolve to various kinds of compiler magic that

** would generate warning messages when they were used.  But that

** compiler magic ended up generating such a flurry of bug reports

** that we have taken it all out and gone back to using simple

** noop macros.

*/

#define SQLITE_DEPRECATED

#define SQLITE_EXPERIMENTAL

 

/*

** Ensure these symbols were not defined by some previous header file.

*/

//如果SQLITE_VERSION、SQLITE_VERSION_NUMBER标志已经定义，则取消

#ifdef SQLITE_VERSION

# undef SQLITE_VERSION

#endif

#ifdef SQLITE_VERSION_NUMBER

# undef SQLITE_VERSION_NUMBER

#endif

 

/*

** CAPI3REF: Compile-Time Library Version Numbers

** SQLITE_VERSION 宏为版本号，[X.Y.Z的SQLITE版本号中,X是主版本号，Y

**是次版本号，Z是发行号

** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header

** evaluates to a string literal that is the SQLite version in the

** format "X.Y.Z" where X is the major version number (always 3 for

** SQLite3) and Y is the minor version number and Z is the release number.)^

** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves

** to an integer with the value (X*1000000 + Y*1000 + Z) where X, Y,

**and Z are the same numbers used in [SQLITE_VERSION].)^

** SQLITE_VERSION_NUMBER根据SQLITE_VERSION中版本号计算一个

**整数（X*1000000 + Y*1000 + Z）

** The SQLITE_VERSION_NUMBER for any given release of SQLite will also

** be larger than the release from which it is derived.  Either Y will

** be held constant and Z will be incremented or else Y will be incremented

** and Z will be reset to zero.

**

** Since version 3.6.18, SQLite source code has been stored in the

** <a href="http://www.fossil-scm.org/">Fossil configuration management

** system</a>.  ^The SQLITE_SOURCE_ID macro evalutes to

** a string which identifies a particular check-in of SQLite

** within its configuration management system.  ^The SQLITE_SOURCE_ID

** string contains the date and time of the check-in (UTC) and an SHA1

** hash of the entire source tree.

** SQLITE_SOURCE_ID 为一个字符串，为SQLITE配置管理系统中的check-in

**详情包含check-in的日期和时间以及整个源码树的SHA1哈希

** See also: [sqlite3_libversion()],

** [sqlite3_libversion_number()], [sqlite3_sourceid()],

** [sqlite_version()] and [sqlite_source_id()].

*/

//定义版本号，并计算SQLITE_VERSION_NUMBER

#define SQLITE_VERSION        "3.6.23.1"

#define SQLITE_VERSION_NUMBER 3006023

#define SQLITE_SOURCE_ID      "2010-03-26 22:28:06 b078b588d617e07886ad156e9f54ade6d823568e"

 

/*

** CAPI3REF: Run-Time Library Version Numbers

** KEYWORDS: sqlite3_version, sqlite3_sourceid

** 这些接口通过库而不是头文件提供了

*SQLITE_VERSION、SQLITE_VERSION_NUMBER以**及SQLITE_SOURCE_ID宏

**的相同信息

** These interfaces provide the same information as the [SQLITE_VERSION],

** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros

** but are associated with the library instead of the header file.  ^(Cautious

** programmers might include assert() statements in their application to

** verify that values returned by these interfaces match the macros in

** the header, and thus insure that the application is

** compiled with matching library and header files.

**可小心地通过包含以下的assert()声明，在应用程序核实匹配头文件中宏的

**这些接口，以确保应用程序使用相匹配的库和头文件编译

** <blockquote><pre>

** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );

** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );

** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );

** </pre></blockquote>)^

** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]

** macro.  ^The sqlite3_libversion() function returns a pointer to the

** to the sqlite3_version[] string constant.  The sqlite3_libversion()

** function is provided for use in DLLs since DLL users usually do not have

** direct access to string constants within the DLL.  ^The

** sqlite3_libversion_number() function returns an integer equal to

** [SQLITE_VERSION_NUMBER].  ^The sqlite3_sourceid() function returns 

** a pointer to a string constant whose value is the same as the 

** [SQLITE_SOURCE_ID] C preprocessor macro.

**

** See also: [sqlite_version()] and [sqlite_source_id()].

*/

SQLITE_API const char sqlite3_version[] = SQLITE_VERSION;

SQLITE_API const char *sqlite3_libversion(void);

SQLITE_API const char *sqlite3_sourceid(void);

SQLITE_API int sqlite3_libversion_number(void);

//SQLITE_VERSION 宏定义了版本号，在本源码包中定义为"3.6.23.1"

//sqlite3_version[]为前面定义的SQLITE_VERSION宏的内容，即版本号

//sqlite3_libversion()返回指向sqlite3_version[]字符数组常量的指针

//sqlite3_sourceid()返回一个指向SQLITE_SOURCE_ID宏内容的指针

//sqlite3_libversion_number()返回SQLITE_VERSION_NUMBER宏定义的版本号

#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS

/*

** CAPI3REF: Run-Time Library Compilation Options Diagnostics

**

** ^The sqlite3_compileoption_used() function returns 0 or 1 

** indicating whether the specified option was defined at 

** compile time.  ^The SQLITE_ prefix may be omitted from the 

** option name passed to sqlite3_compileoption_used().  

**sqlite3_compileoption_used()返回0和1,指示编译时是否有定义的选项

** ^The sqlite3_compileoption_get() function allows interating

** over the list of options that were defined at compile time by

** returning the N-th compile time option string.  ^If N is out of range,

**sqlite3_compileoption_get()允许正在起作用的编译时定义的选项列表，

**返回N次编译时的选项字符串

** sqlite3_compileoption_get() returns a NULL pointer.  ^The SQLITE_ 

** prefix is omitted from any strings returned by 

** sqlite3_compileoption_get().

**如果 N过界，sqlite3_compileoption_get()返回NULL指针

** ^Support for the diagnostic functions sqlite3_compileoption_used()

** and sqlite3_compileoption_get() may be omitted by specifing the 

** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.

**编译时定义SQLITE_OMIT_COMPILEOPTION_DIAGS选项，将忽略sqlite3_compileoption_used()和 sqlite3_compileoption_get()这2个诊断函数

** See also: SQL functions [sqlite_compileoption_used()] and

** [sqlite_compileoption_get()] and the [compile_options pragma].

*/

SQLITE_API int sqlite3_compileoption_used(const char *zOptName);

SQLITE_API const char *sqlite3_compileoption_get(int N);

#endif /* SQLITE_OMIT_COMPILEOPTION_DIAGS */

本SQLite源码剖析系列为刘兴(http://deepfuture.iteye.com/)原创，未经笔者授权，任何人和机构不能转载

** CAPI3REF: 64-Bit Integer Types

** KEYWORDS: sqlite_int64 sqlite_uint64

**64位整数类型

**关键字：sqlite_int64 sqlite_uint64

 

** Because there is no cross-platform way to specify 64-bit integer types

** SQLite includes typedefs for 64-bit signed and unsigned integers.

**没有跨平台的方法定义64位整数，SQLite包括64位有符号和无符号整数

** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.

**sqlite3_int64和sqlite3_uint64是首选类型， sqlite_int64和***sqlite_uint64仅支持向后兼容性。

** The sqlite_int64 and sqlite_uint64 types are supported for backwards

** compatibility only.

**sqlite3_int64 和 sqlite_int64 类型的范围在-922337203685477580

**和+9223372036854775807之间,sqlite3_uint64 和sqlite_uint64在

** 0 和 +18446744073709551615 之间

** ^The sqlite3_int64 and sqlite_int64 types can store integer values

** between -9223372036854775808 and +9223372036854775807 inclusive.  ^The

** sqlite3_uint64 and sqlite_uint64 types can store integer values

** between 0 and +18446744073709551615 inclusive.

*/

//以下根据前面定义的宏，定义sqlite_int64、sqlite_uint64、sqlite3_int64、sqlite_uint64实际使用的类型

#ifdef SQLITE_INT64_TYPE

  typedef SQLITE_INT64_TYPE sqlite_int64;

  typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;

#elif defined(_MSC_VER) || defined(__BORLANDC__)

  typedef __int64 sqlite_int64;

  typedef unsigned __int64 sqlite_uint64;

#else

  typedef long long int sqlite_int64;

  typedef unsigned long long int sqlite_uint64;

#endif

typedef sqlite_int64 sqlite3_int64;

typedef sqlite_uint64 sqlite3_uint64;

/*如果处理器没有符点支持，则用sqlite3_int64整数替代

** If compiling for a processor that lacks floating point support,

** substitute integer for floating-point.

*/

#ifdef SQLITE_OMIT_FLOATING_POINT

# define double sqlite3_int64

#endif

 

/*

** CAPI3REF: Closing A Database Connection

**关闭数据库连接，如果sqlite3对象成功卸载,所有相关资源被释放

**sqlite3sqlite3_close()返回SQLITE_OK

** ^The sqlite3_close() routine is the destructor for the [sqlite3] object.

** ^Calls to sqlite3_close() return SQLITE_OK if the [sqlite3] object is

** successfullly destroyed and all associated resources are deallocated.

**应用程序必须在关闭sqlite3对象前，[sqlite3_finalize | finalize]

**所有的与该对象相关的[prepared statements]，必须[sqlite3_blob_close | **close]所有的与该对象相关的

**[BLOB handles] (BLOB大二进制句柄)

** Applications must [sqlite3_**finalize | finalize] all [prepared statements]

** and [sqlite3_blob_close | close] all [BLOB handles] associated with

** the [sqlite3] object prior to attempting to close the object.  ^If

** sqlite3_close() is called on a [database connection] that still has

** outstanding [prepared statements] or [BLOB handles], then it returns

** SQLITE_BUSY.

**如果sqlite3_close()在[database connection]数据库连接被调用，该数

**据库连接中仍有显式的[prepared statements][BLOB handles]，则返回

**SQLITE_BUSY。当事务打开时，调用sqlite3_close()，事务自动回滚。

** ^If [sqlite3_close()] is invoked while a transaction is open,

** the transaction is automatically rolled back.

**sqlite3_close(C)的C参数可以是NULL指针或从sqlite3_open()、sqlite3_**open16()、sqlite3_open_v2()获取的[sqlite3]对象指针

**使用NULL参数调用sqlite3_close()为没负作用的空操作

** The C parameter to [sqlite3_close(C)] must be either a NULL

** pointer or an [sqlite3] object pointer obtained

** from [sqlite3_open()], [sqlite3_open16()], or

** [sqlite3_open_v2()], and not previously closed.

** ^Calling sqlite3_close() with a NULL pointer argument is a 

** harmless no-op.

*/

SQLITE_API int sqlite3_close(sqlite3 *);

/*

** The type for a callback function.

** This is legacy and deprecated.  It is included for historical

** compatibility and is not documented.

*/回调函数，不赞成这种旧版本遗留下来的机制，它被包含进来，为了历史兼

**容性,没有相关证实

typedef int (*sqlite3_callback)(void*,int,char**, char**);

 

/*

** CAPI3REF: One-Step Query Execution Interface

**查询执行接口

** The sqlite3_exec() interface is a convenience wrapper around

** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],

** that allows an application to run multiple statements of SQL

** without having to use a lot of C code. 

**sqlite3_exec()接口包装了[sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]，方便使用，允许应用程序执行多语句的SQL，无使用大量C代码

**sqlite3_exec()符合UTF8编码要求 ，用分号分隔的SQL语句为它的第二个

**参数，database connection数据 库连接为第一个参数，做为第三个参数的回调函数如果非空，则SQL执行结果的每一行都会调用该函数

** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,

** semicolon-separate SQL statements passed into its 2nd argument,

** in the context of the [database connection] passed in as its 1st

** argument.  ^If the callback function of the 3rd argument to

** sqlite3_exec() is not NULL, then it is invoked for each result row

** coming out of the evaluated SQL statements. 

//第一个参数的每个回调请求被转到sqlite3_exec() 的第4个参数，

//如果指向sqlite3_exec()的回调指针是NULL，则没有回调被调用，

//且结果行被忽略。

**^The 4th argument to

** to sqlite3_exec() is relayed through to the 1st argument of each

** callback invocation.  ^If the callback pointer to sqlite3_exec()

** is NULL, then no callback is ever invoked and result rows are

** ignored.

**当执行SQL语句时，如果错误发生在sqlite3_exec()中,则当前语句

**的执行停止，且子语句被跳过。如果sqlite3_exec()的第5个参

**数非NULL，则error信息被写入从sqlite3_malloc()分配的内存。为防

**内存泄露，应用程序必须调用sqlite3_free()释放从sqlite3_exec()的

**第5个参数返回的错误信息字符串，当这些错误信息字符串不再需要时。

**如果sqlite3_exec()的第5个参数为非NULL且没有错误发生，

**sqlite3_exec()返回前将设置其为NULL

** ^If an error occurs while evaluating the SQL statements passed into

** sqlite3_exec(), then execution of the current statement stops and

** subsequent statements are skipped.  ^If the 5th parameter to sqlite3_exec()

** is not NULL then any error message is written into memory obtained

** from [sqlite3_malloc()] and passed back through the 5th parameter.

** To avoid memory leaks, the application should invoke [sqlite3_free()]

** on error message strings returned through the 5th parameter of

** of sqlite3_exec() after the error message string is no longer needed.

** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors

** occur, then sqlite3_exec() sets the pointer in its 5th parameter to

** NULL before returning.

**如果sqlite3_exec()回调返回非0,则sqlite3_exec()通常

**返回SQLITE_ABORT，不运行任何后来的SQL语句

** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()

** routine returns SQLITE_ABORT without invoking the callback again and

** without running any subsequent SQL statements.

最后

以上就是优秀月光为你收集整理的SQLite源码剖析的全部内容，希望文章能够帮你解决SQLite源码剖析所遇到的程序开发问题。

如果觉得靠谱客网站的内容还不错，欢迎将靠谱客网站推荐给程序员好友。