/ Check-in [2eadef90]
Login

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

Overview
Comment:Documentation fixes. No changes to code. Tickets #2622 and #2624. (CVS 4394)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 2eadef90162590a7b947c38acf0016d0c55821c7
User & Date: drh 2007-09-04 12:00:00
Context
2007-09-04
12:18
Clarify documentation on the return value from sqlite3_column_blob() for a zero-length BLOB. Clarify the documentation on what happens when you have a zeroblob() with a negative length. Additional test cases but no changes to code. Ticket #2623. (CVS 4395) check-in: 63ca02a5 user: drh tags: trunk
12:00
Documentation fixes. No changes to code. Tickets #2622 and #2624. (CVS 4394) check-in: 2eadef90 user: drh tags: trunk
03:28
Fix yet another typo on the homepage. Ticket #2621. (CVS 4393) check-in: d5fec873 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

    26     26   ** on how SQLite interfaces are suppose to operate.
    27     27   **
    28     28   ** The name of this file under configuration management is "sqlite.h.in".
    29     29   ** The makefile makes some minor changes to this file (such as inserting
    30     30   ** the version number) and changes its name to "sqlite3.h" as
    31     31   ** part of the build process.
    32     32   **
    33         -** @(#) $Id: sqlite.h.in,v 1.256 2007/09/03 20:32:45 drh Exp $
           33  +** @(#) $Id: sqlite.h.in,v 1.257 2007/09/04 12:00:00 drh Exp $
    34     34   */
    35     35   #ifndef _SQLITE3_H_
    36     36   #define _SQLITE3_H_
    37     37   #include <stdarg.h>     /* Needed for the definition of va_list */
    38     38   
    39     39   /*
    40     40   ** Make sure we can call this stuff from C++.
................................................................................
   459    459   ** OS-X style fullsync.  The SQLITE_SYNC_DATA flag may be ORed in to
   460    460   ** indicate that only the data of the file and not its inode needs to be
   461    461   ** synced.
   462    462   ** 
   463    463   ** The integer values to xLock() and xUnlock() are one of
   464    464   ** <ul>
   465    465   ** <li> [SQLITE_LOCK_NONE],
   466         -** <li> [SQLITE_LOCK_READ],
          466  +** <li> [SQLITE_LOCK_SHARED],
   467    467   ** <li> [SQLITE_LOCK_RESERVED],
   468    468   ** <li> [SQLITE_LOCK_PENDING], or
   469    469   ** <li> [SQLITE_LOCK_EXCLUSIVE].
   470    470   ** </ul>
   471    471   ** xLock() increases the lock. xUnlock() decreases the lock.  
   472    472   ** The xCheckReservedLock() method looks
   473    473   ** to see if any database connection, either in this
................................................................................
   522    522   ** information is written to disk in the same order as calls
   523    523   ** to xWrite().
   524    524   */
   525    525   typedef struct sqlite3_io_methods sqlite3_io_methods;
   526    526   struct sqlite3_io_methods {
   527    527     int iVersion;
   528    528     int (*xClose)(sqlite3_file*);
   529         -  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite_int64 iOfst);
   530         -  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite_int64 iOfst);
   531         -  int (*xTruncate)(sqlite3_file*, sqlite_int64 size);
          529  +  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
          530  +  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
          531  +  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
   532    532     int (*xSync)(sqlite3_file*, int flags);
   533         -  int (*xFileSize)(sqlite3_file*, sqlite_int64 *pSize);
          533  +  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
   534    534     int (*xLock)(sqlite3_file*, int);
   535    535     int (*xUnlock)(sqlite3_file*, int);
   536    536     int (*xCheckReservedLock)(sqlite3_file*);
   537    537     int (*xFileControl)(sqlite3_file*, int op, void *pArg);
   538    538     int (*xSectorSize)(sqlite3_file*);
   539    539     int (*xDeviceCharacteristics)(sqlite3_file*);
   540    540     /* Additional methods may be added in future releases */
................................................................................
   581    581   ** object when the iVersion value is increased.
   582    582   **
   583    583   ** The szOsFile field is the size of the subclassed [sqlite3_file]
   584    584   ** structure used by this VFS.  mxPathname is the maximum length of
   585    585   ** a pathname in this VFS.
   586    586   **
   587    587   ** Registered vfs modules are kept on a linked list formed by
   588         -** the pNext pointer.  The [sqlite3_register_vfs()]
   589         -** and [sqlite3_unregister_vfs()] interfaces manage this list
   590         -** in a thread-safe way.  The [sqlite3_find_vfs()] interface
          588  +** the pNext pointer.  The [sqlite3_vfs_register()]
          589  +** and [sqlite3_vfs_unregister()] interfaces manage this list
          590  +** in a thread-safe way.  The [sqlite3_vfs_find()] interface
   591    591   ** searches the list.
   592    592   **
   593    593   ** The pNext field is the only fields in the sqlite3_vfs 
   594    594   ** structure that SQLite will ever modify.  SQLite will only access
   595    595   ** or modify this field while holding a particular static mutex.
   596    596   ** The application should never modify anything within the sqlite3_vfs
   597    597   ** object once the object has been registered.
................................................................................
   800    800   ** CAPI3REF: Total Number Of Rows Modified
   801    801   ***
   802    802   ** This function returns the number of database rows that have been
   803    803   ** modified by INSERT, UPDATE or DELETE statements since the database handle
   804    804   ** was opened. This includes UPDATE, INSERT and DELETE statements executed
   805    805   ** as part of trigger programs. All changes are counted as soon as the
   806    806   ** statement that makes them is completed (when the statement handle is
   807         -** passed to [sqlite3_reset()] or [sqlite3_finalise()]).
          807  +** passed to [sqlite3_reset()] or [sqlite3_finalize()]).
   808    808   **
   809    809   ** See also the [sqlite3_change()] interface.
   810    810   **
   811    811   ** SQLite implements the command "DELETE FROM table" without a WHERE clause
   812    812   ** by dropping and recreating the table.  (This is much faster than going
   813    813   ** through and deleting individual elements form the table.)  Because of
   814    814   ** this optimization, the change count for "DELETE FROM table" will be
................................................................................
  1110   1110   char *sqlite3_vmprintf(const char*, va_list);
  1111   1111   char *sqlite3_snprintf(int,char*,const char*, ...);
  1112   1112   
  1113   1113   /*
  1114   1114   ** CAPI3REF: Memory Allocation Subsystem
  1115   1115   **
  1116   1116   ** The SQLite core uses these three routines for all of its own
  1117         -** internal memory allocation needs. The default implementation
         1117  +** internal memory allocation needs. (See the exception below.)
         1118  +** The default implementation
  1118   1119   ** of the memory allocation subsystem uses the malloc(), realloc()
  1119   1120   ** and free() provided by the standard C library.  However, if 
  1120   1121   ** SQLite is compiled with the following C preprocessor macro
  1121   1122   **
  1122   1123   ** <blockquote> SQLITE_OMIT_MEMORY_ALLOCATION </blockquote>
  1123   1124   **
  1124   1125   ** then no implementation is provided for these routines by
  1125   1126   ** SQLite.  The application that links against SQLite is
  1126   1127   ** expected to provide its own implementation.  If the application
  1127   1128   ** does provide its own implementation for these routines, then
  1128         -** it must also provide an implementation for
  1129         -** [sqlite3_memory_alarm()].
         1129  +** it must also provide an implementations for
         1130  +** [sqlite3_memory_alarm()], [sqlite3_memory_used()], and
         1131  +** [sqlite3_memory_highwater()].  The alternative implementations
         1132  +** for these last three routines need not actually work, but
         1133  +** stub functions at least are needed to statisfy the linker.
         1134  +** SQLite never calls [sqlite3_memory_highwater()] itself, but
         1135  +** the symbol is included in a table as part of the
         1136  +** [sqlite3_load_extension()] interface.  The
         1137  +** [sqlite3_memory_alarm()] and [sqlite3_memory_used()] interfaces
         1138  +** are called by [sqlite3_soft_heap_limit()] and working implementations
         1139  +** of both routines must be provided if [sqlite3_soft_heap_limit()]
         1140  +** is to operate correctly.
  1130   1141   **
  1131   1142   ** <b>Exception:</b> The windows OS interface layer calls
  1132   1143   ** the system malloc() and free() directly when converting
  1133   1144   ** filenames between the UTF-8 encoding used by SQLite
  1134   1145   ** and whatever filename encoding is used by the particular windows
  1135   1146   ** installation.  Memory allocation errors are detected, but
  1136   1147   ** they are reported back as [SQLITE_CANTOPEN] or
................................................................................
  1148   1159   ** the memory allocation subsystem included with the SQLite
  1149   1160   ** sources provides the interfaces shown below.
  1150   1161   **
  1151   1162   ** The first of these two routines returns the amount of memory 
  1152   1163   ** currently outstanding (malloced but not freed).  The second
  1153   1164   ** returns the largest instantaneous amount of outstanding
  1154   1165   ** memory.  The highwater mark is reset if the argument is
  1155         -** true.  The SQLite core does not use either of these routines
  1156         -** and so they do not have to be implemented by the application
  1157         -** if SQLITE_OMIT_MEMORY_ALLOCATION is defined.  These routines
  1158         -** are provided by the default memory subsystem for diagnostic
  1159         -** purposes.
         1166  +** true.
         1167  +**
         1168  +** The implementation of these routines in the SQLite core
         1169  +** is omitted if the application is compiled with the
         1170  +** SQLITE_OMIT_MEMORY_ALLOCATION macro defined.  In that case,
         1171  +** the application that links SQLite must provide its own
         1172  +** alternative implementation.  See the documentation on
         1173  +** [sqlite3_malloc()] for additional information.
  1160   1174   */
  1161   1175   sqlite3_int64 sqlite3_memory_used(void);
  1162   1176   sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
  1163   1177   
  1164   1178   /*
  1165   1179   ** CAPI3REF: Memory Allocation Alarms
  1166   1180   **
................................................................................
  2126   2140   ** sqlite3_column_blob() with calls to sqlite3_column_bytes16().  And do not
  2127   2141   ** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().
  2128   2142   **
  2129   2143   ** The pointers returned are valid until a type conversion occurs as
  2130   2144   ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
  2131   2145   ** [sqlite3_finalize()] is called.  The memory space used to hold strings
  2132   2146   ** and blobs is freed automatically.  Do <b>not</b> pass the pointers returned
  2133         -** [sqlite3_column_blob()], [sqlite_column_text()], etc. into 
         2147  +** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into 
  2134   2148   ** [sqlite3_free()].
  2135   2149   **
  2136   2150   ** If a memory allocation error occurs during the evaluation of any
  2137   2151   ** of these routines, a default value is returned.  The default value
  2138   2152   ** is either the integer 0, the floating point number 0.0, or a NULL
  2139   2153   ** pointer.  Subsequent calls to [sqlite3_errcode()] will return
  2140   2154   ** [SQLITE_NOMEM].
................................................................................
  3194   3208   ** CAPI3REF: A Handle To An Open BLOB
  3195   3209   **
  3196   3210   ** An instance of the following opaque structure is used to 
  3197   3211   ** represent an blob-handle.  A blob-handle is created by
  3198   3212   ** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()].
  3199   3213   ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
  3200   3214   ** can be used to read or write small subsections of the blob.
  3201         -** The [sqltie3_blob_size()] interface returns the size of the
         3215  +** The [sqlite3_blob_bytes()] interface returns the size of the
  3202   3216   ** blob in bytes.
  3203   3217   */
  3204   3218   typedef struct sqlite3_blob sqlite3_blob;
  3205   3219   
  3206   3220   /*
  3207   3221   ** CAPI3REF: Open A BLOB For Incremental I/O
  3208   3222   **