/ Check-in [c16b9bec]
Login

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

Overview
Comment:Fix some documentation comments in sqlite.h.in. No functional code changes.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: c16b9bec77c8b9120b728f8431648d95175a83b8
User & Date: drh 2009-12-12 23:57:36
Context
2009-12-13
22:20
Minor documentation updates. No functional changes. check-in: 6ae7e40b user: drh tags: trunk
2009-12-12
23:57
Fix some documentation comments in sqlite.h.in. No functional code changes. check-in: c16b9bec user: drh tags: trunk
19:15
Tests to cover a few extra branches in fts3.c. check-in: 06b72b00 user: dan tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

  1214   1214   ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1215   1215   ** the entire mutexing subsystem is omitted from the build and hence calls to
  1216   1216   ** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
  1217   1217   ** return [SQLITE_ERROR].</dd>
  1218   1218   **
  1219   1219   ** <dt>SQLITE_CONFIG_LOOKASIDE</dt>
  1220   1220   ** <dd> ^(This option takes two arguments that determine the default
  1221         -** memory allocation lookaside optimization.  The first argument is the
         1221  +** memory allocation for the lookaside memory allocator on each
         1222  +** [database connection].  The first argument is the
  1222   1223   ** size of each lookaside buffer slot and the second is the number of
  1223   1224   ** slots allocated to each database connection.)^  ^(This option sets the
  1224   1225   ** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
  1225   1226   ** verb to [sqlite3_db_config()] can be used to change the lookaside
  1226   1227   ** configuration on individual connections.)^ </dd>
  1227   1228   **
  1228   1229   ** <dt>SQLITE_CONFIG_PCACHE</dt>
................................................................................
  2707   2708   */
  2708   2709   const char *sqlite3_column_name(sqlite3_stmt*, int N);
  2709   2710   const void *sqlite3_column_name16(sqlite3_stmt*, int N);
  2710   2711   
  2711   2712   /*
  2712   2713   ** CAPI3REF: Source Of Data In A Query Result
  2713   2714   **
  2714         -** ^These routines provide a means to determine what column of what
  2715         -** table in which database a result of a [SELECT] statement comes from.
         2715  +** ^These routines provide a means to determine the database, table, and
         2716  +** table column that is the origin of a particular result column in
         2717  +** [SELECT] statement.
  2716   2718   ** ^The name of the database or table or column can be returned as
  2717   2719   ** either a UTF-8 or UTF-16 string.  ^The _database_ routines return
  2718   2720   ** the database name, the _table_ routines return the table name, and
  2719   2721   ** the origin_ routines return the column name.
  2720   2722   ** ^The returned string is valid until the [prepared statement] is destroyed
  2721   2723   ** using [sqlite3_finalize()] or until the same information is requested
  2722   2724   ** again in a different encoding.
  2723   2725   **
  2724   2726   ** ^The names returned are the original un-aliased names of the
  2725   2727   ** database, table, and column.
  2726   2728   **
  2727         -** ^The first argument these interfaces is a [prepared statement].
  2728         -** ^These functions return information about the Nth column returned by
         2729  +** ^The first argument to these interfaces is a [prepared statement].
         2730  +** ^These functions return information about the Nth result column returned by
  2729   2731   ** the statement, where N is the second function argument.
  2730         -** ^The left-most column is column 0 for these interface.
         2732  +** ^The left-most column is column 0 for these routines.
  2731   2733   **
  2732   2734   ** ^If the Nth column returned by the statement is an expression or
  2733   2735   ** subquery and is not a column value, then all of these functions return
  2734   2736   ** NULL.  ^These routine might also return NULL if a memory allocation error
  2735   2737   ** occurs.  ^Otherwise, they return the name of the attached database, table
  2736   2738   ** or column that query result column was extracted from.
  2737   2739   **
  2738         -** ^As with all other SQLite APIs, those postfixed with "16" return
  2739         -** UTF-16 encoded strings, the other functions return UTF-8.
         2740  +** ^As with all other SQLite APIs, those whose names end with "16" return
         2741  +** UTF-16 encoded strings and the other functions return UTF-8.
  2740   2742   **
  2741   2743   ** ^These APIs are only available if the library was compiled with the
  2742         -** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined.
         2744  +** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
  2743   2745   **
  2744   2746   ** If two or more threads call one or more of these routines against the same
  2745   2747   ** prepared statement and column at the same time then the results are
  2746   2748   ** undefined.
  2747   2749   **
  2748   2750   ** If two or more threads call one or more
  2749   2751   ** [sqlite3_column_database_name | column metadata interfaces]
................................................................................
  3618   3620   );
  3619   3621   
  3620   3622   /*
  3621   3623   ** CAPI3REF: Collation Needed Callbacks
  3622   3624   **
  3623   3625   ** ^To avoid having to register all collation sequences before a database
  3624   3626   ** can be used, a single callback function may be registered with the
  3625         -** [database connection] to be called whenever an undefined collation
         3627  +** [database connection] to be invoked whenever an undefined collation
  3626   3628   ** sequence is required.
  3627   3629   **
  3628   3630   ** ^If the function is registered using the sqlite3_collation_needed() API,
  3629   3631   ** then it is passed the names of undefined collation sequences as strings
  3630   3632   ** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
  3631   3633   ** the names are passed as UTF-16 in machine native byte order.
  3632         -** ^A call to either function replaces any existing callback.
         3634  +** ^A call to either function replaces the existing collation-needed callback.
  3633   3635   **
  3634   3636   ** ^(When the callback is invoked, the first argument passed is a copy
  3635   3637   ** of the second argument to sqlite3_collation_needed() or
  3636   3638   ** sqlite3_collation_needed16().  The second argument is the database
  3637   3639   ** connection.  The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
  3638   3640   ** or [SQLITE_UTF16LE], indicating the most desirable form of the collation
  3639   3641   ** sequence function required.  The fourth parameter is the name of the
................................................................................
  5096   5098   
  5097   5099   /*
  5098   5100   ** CAPI3REF: Prepared Statement Status
  5099   5101   ** EXPERIMENTAL
  5100   5102   **
  5101   5103   ** ^(Each prepared statement maintains various
  5102   5104   ** [SQLITE_STMTSTATUS_SORT | counters] that measure the number
  5103         -** of times it has performed specific operations.)  These counters can
         5105  +** of times it has performed specific operations.)^  These counters can
  5104   5106   ** be used to monitor the performance characteristics of the prepared
  5105   5107   ** statements.  For example, if the number of table steps greatly exceeds
  5106   5108   ** the number of table searches or result rows, that would tend to indicate
  5107   5109   ** that the prepared statement is using a full table scan rather than
  5108   5110   ** an index.  
  5109   5111   **
  5110   5112   ** ^(This interface is used to retrieve and reset counter values from
................................................................................
  5177   5179   **
  5178   5180   ** ^(The contents of the sqlite3_pcache_methods structure are copied to an
  5179   5181   ** internal buffer by SQLite within the call to [sqlite3_config].  Hence
  5180   5182   ** the application may discard the parameter after the call to
  5181   5183   ** [sqlite3_config()] returns.)^
  5182   5184   **
  5183   5185   ** ^The xInit() method is called once for each call to [sqlite3_initialize()]
  5184         -** (usually only once during the lifetime of the process). ^It is passed
  5185         -** a copy of the sqlite3_pcache_methods.pArg value. ^It can be used to set
  5186         -** up global structures and mutexes required by the custom page cache 
  5187         -** implementation. 
         5186  +** (usually only once during the lifetime of the process). ^(The xInit()
         5187  +** method is passed a copy of the sqlite3_pcache_methods.pArg value.)^
         5188  +** ^The xInit() method can set up up global structures and/or any mutexes
         5189  +** required by the custom page cache implementation. 
  5188   5190   **
  5189   5191   ** ^The xShutdown() method is called from within [sqlite3_shutdown()], 
  5190   5192   ** if the application invokes this API. It can be used to clean up 
  5191   5193   ** any outstanding resources before process shutdown, if required.
  5192   5194   **
  5193   5195   ** ^SQLite holds a [SQLITE_MUTEX_RECURSIVE] mutex when it invokes
  5194   5196   ** the xInit method, so the xInit method need not be threadsafe.  ^The
................................................................................
  5371   5373   ** sqlite3_backup_finish() functions to perform the specified backup 
  5372   5374   ** operation.
  5373   5375   **
  5374   5376   ** <b>sqlite3_backup_step()</b>
  5375   5377   **
  5376   5378   ** ^Function sqlite3_backup_step(B,N) will copy up to N pages between 
  5377   5379   ** the source and destination databases specified by [sqlite3_backup] object B.
  5378         -** ^If N is negative value, all remaining source pages are copied. 
         5380  +** ^If N is negative, all remaining source pages are copied. 
  5379   5381   ** ^If sqlite3_backup_step(B,N) successfully copies N pages and there
  5380   5382   ** are still more pages to be copied, then the function resturns [SQLITE_OK].
  5381   5383   ** ^If sqlite3_backup_step(B,N) successfully finishes copying all pages
  5382   5384   ** from source to destination, then it returns [SQLITE_DONE].
  5383   5385   ** ^If an error occurs while running sqlite3_backup_step(B,N),
  5384   5386   ** then an [error code] is returned. ^As well as [SQLITE_OK] and
  5385   5387   ** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],