Diff of /SQLite.Interop/src/sqlite3.h [509afd] .. [22b0fd]  Maximize  Restore

  Switch to unified view

a/SQLite.Interop/src/sqlite3.h b/SQLite.Interop/src/sqlite3.h
...
...
105
**
105
**
106
** See also: [sqlite3_libversion()],
106
** See also: [sqlite3_libversion()],
107
** [sqlite3_libversion_number()], [sqlite3_sourceid()],
107
** [sqlite3_libversion_number()], [sqlite3_sourceid()],
108
** [sqlite_version()] and [sqlite_source_id()].
108
** [sqlite_version()] and [sqlite_source_id()].
109
*/
109
*/
110
#define SQLITE_VERSION        "3.6.23.1"
110
#define SQLITE_VERSION        "3.7.0.1"
111
#define SQLITE_VERSION_NUMBER 3006023
111
#define SQLITE_VERSION_NUMBER 3007000
112
#define SQLITE_SOURCE_ID      "2010-03-26 22:28:06 b078b588d617e07886ad156e9f54ade6d823568e"
112
#define SQLITE_SOURCE_ID      "2010-08-04 12:31:11 042a1abb030a0711386add7eb6e10832cc8b0f57"
113
113
114
/*
114
/*
115
** CAPI3REF: Run-Time Library Version Numbers
115
** CAPI3REF: Run-Time Library Version Numbers
116
** KEYWORDS: sqlite3_version, sqlite3_sourceid
116
** KEYWORDS: sqlite3_version, sqlite3_sourceid
117
**
117
**
...
...
144
SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
144
SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
145
SQLITE_API const char *sqlite3_libversion(void);
145
SQLITE_API const char *sqlite3_libversion(void);
146
SQLITE_API const char *sqlite3_sourceid(void);
146
SQLITE_API const char *sqlite3_sourceid(void);
147
SQLITE_API int sqlite3_libversion_number(void);
147
SQLITE_API int sqlite3_libversion_number(void);
148
148
149
#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
150
/*
149
/*
151
** CAPI3REF: Run-Time Library Compilation Options Diagnostics
150
** CAPI3REF: Run-Time Library Compilation Options Diagnostics
152
**
151
**
153
** ^The sqlite3_compileoption_used() function returns 0 or 1 
152
** ^The sqlite3_compileoption_used() function returns 0 or 1 
154
** indicating whether the specified option was defined at 
153
** indicating whether the specified option was defined at 
...
...
167
** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
166
** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
168
**
167
**
169
** See also: SQL functions [sqlite_compileoption_used()] and
168
** See also: SQL functions [sqlite_compileoption_used()] and
170
** [sqlite_compileoption_get()] and the [compile_options pragma].
169
** [sqlite_compileoption_get()] and the [compile_options pragma].
171
*/
170
*/
171
#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
172
SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
172
SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
173
SQLITE_API const char *sqlite3_compileoption_get(int N);
173
SQLITE_API const char *sqlite3_compileoption_get(int N);
174
#endif /* SQLITE_OMIT_COMPILEOPTION_DIAGS */
174
#endif
175
175
176
/*
176
/*
177
** CAPI3REF: Test To See If The Library Is Threadsafe
177
** CAPI3REF: Test To See If The Library Is Threadsafe
178
**
178
**
179
** ^The sqlite3_threadsafe() function returns zero if and only if
179
** ^The sqlite3_threadsafe() function returns zero if and only if
...
...
391
#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
391
#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
392
#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
392
#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
393
#define SQLITE_NOTFOUND    12   /* NOT USED. Table or record not found */
393
#define SQLITE_NOTFOUND    12   /* NOT USED. Table or record not found */
394
#define SQLITE_FULL        13   /* Insertion failed because database is full */
394
#define SQLITE_FULL        13   /* Insertion failed because database is full */
395
#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
395
#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
396
#define SQLITE_PROTOCOL    15   /* NOT USED. Database lock protocol error */
396
#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
397
#define SQLITE_EMPTY       16   /* Database is empty */
397
#define SQLITE_EMPTY       16   /* Database is empty */
398
#define SQLITE_SCHEMA      17   /* The database schema changed */
398
#define SQLITE_SCHEMA      17   /* The database schema changed */
399
#define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
399
#define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
400
#define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
400
#define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
401
#define SQLITE_MISMATCH    20   /* Data type mismatch */
401
#define SQLITE_MISMATCH    20   /* Data type mismatch */
...
...
447
#define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))
447
#define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))
448
#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
448
#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
449
#define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))
449
#define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))
450
#define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))
450
#define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))
451
#define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))
451
#define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))
452
#define SQLITE_IOERR_SHMOPEN           (SQLITE_IOERR | (18<<8))
453
#define SQLITE_IOERR_SHMSIZE           (SQLITE_IOERR | (19<<8))
454
#define SQLITE_IOERR_SHMLOCK           (SQLITE_IOERR | (20<<8))
452
#define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED | (1<<8) )
455
#define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED |  (1<<8))
456
#define SQLITE_BUSY_RECOVERY           (SQLITE_BUSY   |  (1<<8))
457
#define SQLITE_CANTOPEN_NOTEMPDIR      (SQLITE_CANTOPEN | (1<<8))
453
458
454
/*
459
/*
455
** CAPI3REF: Flags For File Open Operations
460
** CAPI3REF: Flags For File Open Operations
456
**
461
**
457
** These bit values are intended for use in the
462
** These bit values are intended for use in the
...
...
474
#define SQLITE_OPEN_MASTER_JOURNAL   0x00004000  /* VFS only */
479
#define SQLITE_OPEN_MASTER_JOURNAL   0x00004000  /* VFS only */
475
#define SQLITE_OPEN_NOMUTEX          0x00008000  /* Ok for sqlite3_open_v2() */
480
#define SQLITE_OPEN_NOMUTEX          0x00008000  /* Ok for sqlite3_open_v2() */
476
#define SQLITE_OPEN_FULLMUTEX        0x00010000  /* Ok for sqlite3_open_v2() */
481
#define SQLITE_OPEN_FULLMUTEX        0x00010000  /* Ok for sqlite3_open_v2() */
477
#define SQLITE_OPEN_SHAREDCACHE      0x00020000  /* Ok for sqlite3_open_v2() */
482
#define SQLITE_OPEN_SHAREDCACHE      0x00020000  /* Ok for sqlite3_open_v2() */
478
#define SQLITE_OPEN_PRIVATECACHE     0x00040000  /* Ok for sqlite3_open_v2() */
483
#define SQLITE_OPEN_PRIVATECACHE     0x00040000  /* Ok for sqlite3_open_v2() */
484
#define SQLITE_OPEN_WAL              0x00080000  /* VFS only */
479
485
480
/*
486
/*
481
** CAPI3REF: Device Characteristics
487
** CAPI3REF: Device Characteristics
482
**
488
**
483
** The xDeviceCapabilities method of the [sqlite3_io_methods]
489
** The xDeviceCharacteristics method of the [sqlite3_io_methods]
484
** object returns an integer which is a vector of the these
490
** object returns an integer which is a vector of the these
485
** bit values expressing I/O characteristics of the mass storage
491
** bit values expressing I/O characteristics of the mass storage
486
** device that holds the file that the [sqlite3_io_methods]
492
** device that holds the file that the [sqlite3_io_methods]
487
** refers to.
493
** refers to.
488
**
494
**
...
...
495
** first then the size of the file is extended, never the other
501
** first then the size of the file is extended, never the other
496
** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
502
** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
497
** information is written to disk in the same order as calls
503
** information is written to disk in the same order as calls
498
** to xWrite().
504
** to xWrite().
499
*/
505
*/
500
#define SQLITE_IOCAP_ATOMIC          0x00000001
506
#define SQLITE_IOCAP_ATOMIC                 0x00000001
501
#define SQLITE_IOCAP_ATOMIC512       0x00000002
507
#define SQLITE_IOCAP_ATOMIC512              0x00000002
502
#define SQLITE_IOCAP_ATOMIC1K        0x00000004
508
#define SQLITE_IOCAP_ATOMIC1K               0x00000004
503
#define SQLITE_IOCAP_ATOMIC2K        0x00000008
509
#define SQLITE_IOCAP_ATOMIC2K               0x00000008
504
#define SQLITE_IOCAP_ATOMIC4K        0x00000010
510
#define SQLITE_IOCAP_ATOMIC4K               0x00000010
505
#define SQLITE_IOCAP_ATOMIC8K        0x00000020
511
#define SQLITE_IOCAP_ATOMIC8K               0x00000020
506
#define SQLITE_IOCAP_ATOMIC16K       0x00000040
512
#define SQLITE_IOCAP_ATOMIC16K              0x00000040
507
#define SQLITE_IOCAP_ATOMIC32K       0x00000080
513
#define SQLITE_IOCAP_ATOMIC32K              0x00000080
508
#define SQLITE_IOCAP_ATOMIC64K       0x00000100
514
#define SQLITE_IOCAP_ATOMIC64K              0x00000100
509
#define SQLITE_IOCAP_SAFE_APPEND     0x00000200
515
#define SQLITE_IOCAP_SAFE_APPEND            0x00000200
510
#define SQLITE_IOCAP_SEQUENTIAL      0x00000400
516
#define SQLITE_IOCAP_SEQUENTIAL             0x00000400
517
#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN  0x00000800
511
518
512
/*
519
/*
513
** CAPI3REF: File Locking Levels
520
** CAPI3REF: File Locking Levels
514
**
521
**
515
** SQLite uses one of these integer values as the second
522
** SQLite uses one of these integer values as the second
...
...
656
  int (*xUnlock)(sqlite3_file*, int);
663
  int (*xUnlock)(sqlite3_file*, int);
657
  int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
664
  int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
658
  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
665
  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
659
  int (*xSectorSize)(sqlite3_file*);
666
  int (*xSectorSize)(sqlite3_file*);
660
  int (*xDeviceCharacteristics)(sqlite3_file*);
667
  int (*xDeviceCharacteristics)(sqlite3_file*);
668
  /* Methods above are valid for version 1 */
669
  int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
670
  int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
671
  void (*xShmBarrier)(sqlite3_file*);
672
  int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
673
  /* Methods above are valid for version 2 */
661
  /* Additional methods may be added in future releases */
674
  /* Additional methods may be added in future releases */
662
};
675
};
663
676
664
/*
677
/*
665
** CAPI3REF: Standard File Control Opcodes
678
** CAPI3REF: Standard File Control Opcodes
...
...
673
** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
686
** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
674
** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
687
** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
675
** into an integer that the pArg argument points to. This capability
688
** into an integer that the pArg argument points to. This capability
676
** is used during testing and only needs to be supported when SQLITE_TEST
689
** is used during testing and only needs to be supported when SQLITE_TEST
677
** is defined.
690
** is defined.
691
**
692
** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
693
** layer a hint of how large the database file will grow to be during the
694
** current transaction.  This hint is not guaranteed to be accurate but it
695
** is often close.  The underlying VFS might choose to preallocate database
696
** file space based on this hint in order to help writes to the database
697
** file run faster.
678
*/
698
*/
679
#define SQLITE_FCNTL_LOCKSTATE        1
699
#define SQLITE_FCNTL_LOCKSTATE        1
680
#define SQLITE_GET_LOCKPROXYFILE      2
700
#define SQLITE_GET_LOCKPROXYFILE      2
681
#define SQLITE_SET_LOCKPROXYFILE      3
701
#define SQLITE_SET_LOCKPROXYFILE      3
682
#define SQLITE_LAST_ERRNO             4
702
#define SQLITE_LAST_ERRNO             4
703
#define SQLITE_FCNTL_SIZE_HINT        5
683
704
684
/*
705
/*
685
** CAPI3REF: Mutex Handle
706
** CAPI3REF: Mutex Handle
686
**
707
**
687
** The mutex module within SQLite defines [sqlite3_mutex] to be an
708
** The mutex module within SQLite defines [sqlite3_mutex] to be an
...
...
809
** is also passed as a parameter to both  methods. If the output buffer
830
** is also passed as a parameter to both  methods. If the output buffer
810
** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
831
** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
811
** handled as a fatal error by SQLite, vfs implementations should endeavor
832
** handled as a fatal error by SQLite, vfs implementations should endeavor
812
** to prevent this by setting mxPathname to a sufficiently large value.
833
** to prevent this by setting mxPathname to a sufficiently large value.
813
**
834
**
814
** The xRandomness(), xSleep(), and xCurrentTime() interfaces
835
** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
815
** are not strictly a part of the filesystem, but they are
836
** interfaces are not strictly a part of the filesystem, but they are
816
** included in the VFS structure for completeness.
837
** included in the VFS structure for completeness.
817
** The xRandomness() function attempts to return nBytes bytes
838
** The xRandomness() function attempts to return nBytes bytes
818
** of good-quality randomness into zOut.  The return value is
839
** of good-quality randomness into zOut.  The return value is
819
** the actual number of bytes of randomness obtained.
840
** the actual number of bytes of randomness obtained.
820
** The xSleep() method causes the calling thread to sleep for at
841
** The xSleep() method causes the calling thread to sleep for at
821
** least the number of microseconds given.  The xCurrentTime()
842
** least the number of microseconds given.  The xCurrentTime()
822
** method returns a Julian Day Number for the current date and time.
843
** method returns a Julian Day Number for the current date and time as
823
**
844
** a floating point value.
845
** The xCurrentTimeInt64() method returns, as an integer, the Julian
846
** Day Number multipled by 86400000 (the number of milliseconds in 
847
** a 24-hour day).  
848
** ^SQLite will use the xCurrentTimeInt64() method to get the current
849
** date and time if that method is available (if iVersion is 2 or 
850
** greater and the function pointer is not NULL) and will fall back
851
** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
824
*/
852
*/
825
typedef struct sqlite3_vfs sqlite3_vfs;
853
typedef struct sqlite3_vfs sqlite3_vfs;
826
struct sqlite3_vfs {
854
struct sqlite3_vfs {
827
  int iVersion;            /* Structure version number */
855
  int iVersion;            /* Structure version number (currently 2) */
828
  int szOsFile;            /* Size of subclassed sqlite3_file */
856
  int szOsFile;            /* Size of subclassed sqlite3_file */
829
  int mxPathname;          /* Maximum file pathname length */
857
  int mxPathname;          /* Maximum file pathname length */
830
  sqlite3_vfs *pNext;      /* Next registered VFS */
858
  sqlite3_vfs *pNext;      /* Next registered VFS */
831
  const char *zName;       /* Name of this virtual file system */
859
  const char *zName;       /* Name of this virtual file system */
832
  void *pAppData;          /* Pointer to application-specific data */
860
  void *pAppData;          /* Pointer to application-specific data */
...
...
841
  void (*xDlClose)(sqlite3_vfs*, void*);
869
  void (*xDlClose)(sqlite3_vfs*, void*);
842
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
870
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
843
  int (*xSleep)(sqlite3_vfs*, int microseconds);
871
  int (*xSleep)(sqlite3_vfs*, int microseconds);
844
  int (*xCurrentTime)(sqlite3_vfs*, double*);
872
  int (*xCurrentTime)(sqlite3_vfs*, double*);
845
  int (*xGetLastError)(sqlite3_vfs*, int, char *);
873
  int (*xGetLastError)(sqlite3_vfs*, int, char *);
874
  /*
875
  ** The methods above are in version 1 of the sqlite_vfs object
876
  ** definition.  Those that follow are added in version 2 or later
877
  */
878
  int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
879
  /*
880
  ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
846
  /* New fields may be appended in figure versions.  The iVersion
881
  ** New fields may be appended in figure versions.  The iVersion
847
  ** value will increment whenever this happens. */
882
  ** value will increment whenever this happens. 
883
  */
848
};
884
};
849
885
850
/*
886
/*
851
** CAPI3REF: Flags for the xAccess VFS method
887
** CAPI3REF: Flags for the xAccess VFS method
852
**
888
**
...
...
854
** the xAccess method of an [sqlite3_vfs] object.  They determine
890
** the xAccess method of an [sqlite3_vfs] object.  They determine
855
** what kind of permissions the xAccess method is looking for.
891
** what kind of permissions the xAccess method is looking for.
856
** With SQLITE_ACCESS_EXISTS, the xAccess method
892
** With SQLITE_ACCESS_EXISTS, the xAccess method
857
** simply checks whether the file exists.
893
** simply checks whether the file exists.
858
** With SQLITE_ACCESS_READWRITE, the xAccess method
894
** With SQLITE_ACCESS_READWRITE, the xAccess method
859
** checks whether the file is both readable and writable.
895
** checks whether the named directory is both readable and writable
896
** (in other words, if files can be added, removed, and renamed within
897
** the directory).
898
** The SQLITE_ACCESS_READWRITE constant is currently used only by the
899
** [temp_store_directory pragma], though this could change in a future
900
** release of SQLite.
860
** With SQLITE_ACCESS_READ, the xAccess method
901
** With SQLITE_ACCESS_READ, the xAccess method
861
** checks whether the file is readable.
902
** checks whether the file is readable.  The SQLITE_ACCESS_READ constant is
903
** currently unused, though it might be used in a future release of
904
** SQLite.
862
*/
905
*/
863
#define SQLITE_ACCESS_EXISTS    0
906
#define SQLITE_ACCESS_EXISTS    0
864
#define SQLITE_ACCESS_READWRITE 1
907
#define SQLITE_ACCESS_READWRITE 1   /* Used by PRAGMA temp_store_directory */
865
#define SQLITE_ACCESS_READ      2
908
#define SQLITE_ACCESS_READ      2   /* Unused */
909
910
/*
911
** CAPI3REF: Flags for the xShmLock VFS method
912
**
913
** These integer constants define the various locking operations
914
** allowed by the xShmLock method of [sqlite3_io_methods].  The
915
** following are the only legal combinations of flags to the
916
** xShmLock method:
917
**
918
** <ul>
919
** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
920
** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
921
** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
922
** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
923
** </ul>
924
**
925
** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
926
** was given no the corresponding lock.  
927
**
928
** The xShmLock method can transition between unlocked and SHARED or
929
** between unlocked and EXCLUSIVE.  It cannot transition between SHARED
930
** and EXCLUSIVE.
931
*/
932
#define SQLITE_SHM_UNLOCK       1
933
#define SQLITE_SHM_LOCK         2
934
#define SQLITE_SHM_SHARED       4
935
#define SQLITE_SHM_EXCLUSIVE    8
936
937
/*
938
** CAPI3REF: Maximum xShmLock index
939
**
940
** The xShmLock method on [sqlite3_io_methods] may use values
941
** between 0 and this upper bound as its "offset" argument.
942
** The SQLite core will never attempt to acquire or release a
943
** lock outside of this range
944
*/
945
#define SQLITE_SHM_NLOCK        8
946
866
947
867
/*
948
/*
868
** CAPI3REF: Initialize The SQLite Library
949
** CAPI3REF: Initialize The SQLite Library
869
**
950
**
870
** ^The sqlite3_initialize() routine initializes the
951
** ^The sqlite3_initialize() routine initializes the
...
...
971
**
1052
**
972
** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
1053
** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
973
** ^If the option is unknown or SQLite is unable to set the option
1054
** ^If the option is unknown or SQLite is unable to set the option
974
** then this routine returns a non-zero [error code].
1055
** then this routine returns a non-zero [error code].
975
*/
1056
*/
976
SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_config(int, ...);
1057
SQLITE_API int sqlite3_config(int, ...);
977
1058
978
/*
1059
/*
979
** CAPI3REF: Configure database connections
1060
** CAPI3REF: Configure database connections
980
** EXPERIMENTAL
981
**
1061
**
982
** The sqlite3_db_config() interface is used to make configuration
1062
** The sqlite3_db_config() interface is used to make configuration
983
** changes to a [database connection].  The interface is similar to
1063
** changes to a [database connection].  The interface is similar to
984
** [sqlite3_config()] except that the changes apply to a single
1064
** [sqlite3_config()] except that the changes apply to a single
985
** [database connection] (specified in the first argument).  The
1065
** [database connection] (specified in the first argument).  The
...
...
995
** Additional arguments depend on the verb.
1075
** Additional arguments depend on the verb.
996
**
1076
**
997
** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
1077
** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
998
** the call is considered successful.
1078
** the call is considered successful.
999
*/
1079
*/
1000
SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...);
1080
SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
1001
1081
1002
/*
1082
/*
1003
** CAPI3REF: Memory Allocation Routines
1083
** CAPI3REF: Memory Allocation Routines
1004
** EXPERIMENTAL
1005
**
1084
**
1006
** An instance of this object defines the interface between SQLite
1085
** An instance of this object defines the interface between SQLite
1007
** and low-level memory allocation routines.
1086
** and low-level memory allocation routines.
1008
**
1087
**
1009
** This object is used in only one place in the SQLite interface.
1088
** This object is used in only one place in the SQLite interface.
...
...
1081
  void *pAppData;                /* Argument to xInit() and xShutdown() */
1160
  void *pAppData;                /* Argument to xInit() and xShutdown() */
1082
};
1161
};
1083
1162
1084
/*
1163
/*
1085
** CAPI3REF: Configuration Options
1164
** CAPI3REF: Configuration Options
1086
** EXPERIMENTAL
1087
**
1165
**
1088
** These constants are the available integer configuration options that
1166
** These constants are the available integer configuration options that
1089
** can be passed as the first argument to the [sqlite3_config()] interface.
1167
** can be passed as the first argument to the [sqlite3_config()] interface.
1090
**
1168
**
1091
** New configuration options may be added in future releases of SQLite.
1169
** New configuration options may be added in future releases of SQLite.
...
...
1267
** <dt>SQLITE_CONFIG_GETPCACHE</dt>
1345
** <dt>SQLITE_CONFIG_GETPCACHE</dt>
1268
** <dd> ^(This option takes a single argument which is a pointer to an
1346
** <dd> ^(This option takes a single argument which is a pointer to an
1269
** [sqlite3_pcache_methods] object.  SQLite copies of the current
1347
** [sqlite3_pcache_methods] object.  SQLite copies of the current
1270
** page cache implementation into that object.)^ </dd>
1348
** page cache implementation into that object.)^ </dd>
1271
**
1349
**
1350
** <dt>SQLITE_CONFIG_LOG</dt>
1351
** <dd> ^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
1352
** function with a call signature of void(*)(void*,int,const char*), 
1353
** and a pointer to void. ^If the function pointer is not NULL, it is
1354
** invoked by [sqlite3_log()] to process each logging event.  ^If the
1355
** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
1356
** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
1357
** passed through as the first parameter to the application-defined logger
1358
** function whenever that function is invoked.  ^The second parameter to
1359
** the logger function is a copy of the first parameter to the corresponding
1360
** [sqlite3_log()] call and is intended to be a [result code] or an
1361
** [extended result code].  ^The third parameter passed to the logger is
1362
** log message after formatting via [sqlite3_snprintf()].
1363
** The SQLite logging interface is not reentrant; the logger function
1364
** supplied by the application must not invoke any SQLite interface.
1365
** In a multi-threaded application, the application-defined logger
1366
** function must be threadsafe. </dd>
1367
**
1272
** </dl>
1368
** </dl>
1273
*/
1369
*/
1274
#define SQLITE_CONFIG_SINGLETHREAD  1  /* nil */
1370
#define SQLITE_CONFIG_SINGLETHREAD  1  /* nil */
1275
#define SQLITE_CONFIG_MULTITHREAD   2  /* nil */
1371
#define SQLITE_CONFIG_MULTITHREAD   2  /* nil */
1276
#define SQLITE_CONFIG_SERIALIZED    3  /* nil */
1372
#define SQLITE_CONFIG_SERIALIZED    3  /* nil */
...
...
1287
#define SQLITE_CONFIG_PCACHE       14  /* sqlite3_pcache_methods* */
1383
#define SQLITE_CONFIG_PCACHE       14  /* sqlite3_pcache_methods* */
1288
#define SQLITE_CONFIG_GETPCACHE    15  /* sqlite3_pcache_methods* */
1384
#define SQLITE_CONFIG_GETPCACHE    15  /* sqlite3_pcache_methods* */
1289
#define SQLITE_CONFIG_LOG          16  /* xFunc, void* */
1385
#define SQLITE_CONFIG_LOG          16  /* xFunc, void* */
1290
1386
1291
/*
1387
/*
1292
** CAPI3REF: Configuration Options
1388
** CAPI3REF: Database Connection Configuration Options
1293
** EXPERIMENTAL
1294
**
1389
**
1295
** These constants are the available integer configuration options that
1390
** These constants are the available integer configuration options that
1296
** can be passed as the second argument to the [sqlite3_db_config()] interface.
1391
** can be passed as the second argument to the [sqlite3_db_config()] interface.
1297
**
1392
**
1298
** New configuration options may be added in future releases of SQLite.
1393
** New configuration options may be added in future releases of SQLite.
...
...
2064
#define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */
2159
#define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */
2065
#define SQLITE_COPY                  0   /* No longer used */
2160
#define SQLITE_COPY                  0   /* No longer used */
2066
2161
2067
/*
2162
/*
2068
** CAPI3REF: Tracing And Profiling Functions
2163
** CAPI3REF: Tracing And Profiling Functions
2069
** EXPERIMENTAL
2070
**
2164
**
2071
** These routines register callback functions that can be used for
2165
** These routines register callback functions that can be used for
2072
** tracing and profiling the execution of SQL statements.
2166
** tracing and profiling the execution of SQL statements.
2073
**
2167
**
2074
** ^The callback function registered by sqlite3_trace() is invoked at
2168
** ^The callback function registered by sqlite3_trace() is invoked at
...
...
2082
** ^The callback function registered by sqlite3_profile() is invoked
2176
** ^The callback function registered by sqlite3_profile() is invoked
2083
** as each SQL statement finishes.  ^The profile callback contains
2177
** as each SQL statement finishes.  ^The profile callback contains
2084
** the original statement text and an estimate of wall-clock time
2178
** the original statement text and an estimate of wall-clock time
2085
** of how long that statement took to run.
2179
** of how long that statement took to run.
2086
*/
2180
*/
2087
SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
2181
SQLITE_API void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
2088
SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
2182
SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
2089
   void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
2183
   void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
2090
2184
2091
/*
2185
/*
2092
** CAPI3REF: Query Progress Callbacks
2186
** CAPI3REF: Query Progress Callbacks
...
...
2875
** already been [sqlite3_finalize | finalized] or on one that had
2969
** already been [sqlite3_finalize | finalized] or on one that had
2876
** previously returned [SQLITE_ERROR] or [SQLITE_DONE].  Or it could
2970
** previously returned [SQLITE_ERROR] or [SQLITE_DONE].  Or it could
2877
** be the case that the same database connection is being used by two or
2971
** be the case that the same database connection is being used by two or
2878
** more threads at the same moment in time.
2972
** more threads at the same moment in time.
2879
**
2973
**
2974
** For all versions of SQLite up to and including 3.6.23.1, it was required
2975
** after sqlite3_step() returned anything other than [SQLITE_ROW] that
2976
** [sqlite3_reset()] be called before any subsequent invocation of
2977
** sqlite3_step().  Failure to invoke [sqlite3_reset()] in this way would
2978
** result in an [SQLITE_MISUSE] return from sqlite3_step().  But after
2979
** version 3.6.23.1, sqlite3_step() began calling [sqlite3_reset()] 
2980
** automatically in this circumstance rather than returning [SQLITE_MISUSE].  
2981
**
2880
** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
2982
** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
2881
** API always returns a generic error code, [SQLITE_ERROR], following any
2983
** API always returns a generic error code, [SQLITE_ERROR], following any
2882
** error other than [SQLITE_BUSY] and [SQLITE_MISUSE].  You must call
2984
** error other than [SQLITE_BUSY] and [SQLITE_MISUSE].  You must call
2883
** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
2985
** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
2884
** specific [error codes] that better describes the error.
2986
** specific [error codes] that better describes the error.
...
...
3687
  sqlite3*, 
3789
  sqlite3*, 
3688
  void*,
3790
  void*,
3689
  void(*)(void*,sqlite3*,int eTextRep,const void*)
3791
  void(*)(void*,sqlite3*,int eTextRep,const void*)
3690
);
3792
);
3691
3793
3692
#if SQLITE_HAS_CODEC
3794
#ifdef SQLITE_HAS_CODEC
3693
/*
3795
/*
3694
** Specify the key for an encrypted database.  This routine should be
3796
** Specify the key for an encrypted database.  This routine should be
3695
** called right after sqlite3_open().
3797
** called right after sqlite3_open().
3696
**
3798
**
3697
** The code to implement this API is not available in the public release
3799
** The code to implement this API is not available in the public release
...
...
3870
** ^For the purposes of this API, a transaction is said to have been
3972
** ^For the purposes of this API, a transaction is said to have been
3871
** rolled back if an explicit "ROLLBACK" statement is executed, or
3973
** rolled back if an explicit "ROLLBACK" statement is executed, or
3872
** an error or constraint causes an implicit rollback to occur.
3974
** an error or constraint causes an implicit rollback to occur.
3873
** ^The rollback callback is not invoked if a transaction is
3975
** ^The rollback callback is not invoked if a transaction is
3874
** automatically rolled back because the database connection is closed.
3976
** automatically rolled back because the database connection is closed.
3875
** ^The rollback callback is not invoked if a transaction is
3876
** rolled back because a commit callback returned non-zero.
3877
**
3977
**
3878
** See also the [sqlite3_update_hook()] interface.
3978
** See also the [sqlite3_update_hook()] interface.
3879
*/
3979
*/
3880
SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
3980
SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
3881
SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
3981
SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
...
...
4157
** ^This function disables automatic extensions in all threads.
4257
** ^This function disables automatic extensions in all threads.
4158
*/
4258
*/
4159
SQLITE_API void sqlite3_reset_auto_extension(void);
4259
SQLITE_API void sqlite3_reset_auto_extension(void);
4160
4260
4161
/*
4261
/*
4162
****** EXPERIMENTAL - subject to change without notice **************
4163
**
4164
** The interface to the virtual-table mechanism is currently considered
4262
** The interface to the virtual-table mechanism is currently considered
4165
** to be experimental.  The interface might change in incompatible ways.
4263
** to be experimental.  The interface might change in incompatible ways.
4166
** If this is a problem for you, do not use the interface at this time.
4264
** If this is a problem for you, do not use the interface at this time.
4167
**
4265
**
4168
** When the virtual-table mechanism stabilizes, we will declare the
4266
** When the virtual-table mechanism stabilizes, we will declare the
...
...
4178
typedef struct sqlite3_module sqlite3_module;
4276
typedef struct sqlite3_module sqlite3_module;
4179
4277
4180
/*
4278
/*
4181
** CAPI3REF: Virtual Table Object
4279
** CAPI3REF: Virtual Table Object
4182
** KEYWORDS: sqlite3_module {virtual table module}
4280
** KEYWORDS: sqlite3_module {virtual table module}
4183
** EXPERIMENTAL
4184
**
4281
**
4185
** This structure, sometimes called a a "virtual table module", 
4282
** This structure, sometimes called a a "virtual table module", 
4186
** defines the implementation of a [virtual tables].  
4283
** defines the implementation of a [virtual tables].  
4187
** This structure consists mostly of methods for the module.
4284
** This structure consists mostly of methods for the module.
4188
**
4285
**
...
...
4225
};
4322
};
4226
4323
4227
/*
4324
/*
4228
** CAPI3REF: Virtual Table Indexing Information
4325
** CAPI3REF: Virtual Table Indexing Information
4229
** KEYWORDS: sqlite3_index_info
4326
** KEYWORDS: sqlite3_index_info
4230
** EXPERIMENTAL
4231
**
4327
**
4232
** The sqlite3_index_info structure and its substructures is used to
4328
** The sqlite3_index_info structure and its substructures is used to
4233
** pass information into and receive the reply from the [xBestIndex]
4329
** pass information into and receive the reply from the [xBestIndex]
4234
** method of a [virtual table module].  The fields under **Inputs** are the
4330
** method of a [virtual table module].  The fields under **Inputs** are the
4235
** inputs to xBestIndex and are read-only.  xBestIndex inserts its
4331
** inputs to xBestIndex and are read-only.  xBestIndex inserts its
...
...
4307
#define SQLITE_INDEX_CONSTRAINT_GE    32
4403
#define SQLITE_INDEX_CONSTRAINT_GE    32
4308
#define SQLITE_INDEX_CONSTRAINT_MATCH 64
4404
#define SQLITE_INDEX_CONSTRAINT_MATCH 64
4309
4405
4310
/*
4406
/*
4311
** CAPI3REF: Register A Virtual Table Implementation
4407
** CAPI3REF: Register A Virtual Table Implementation
4312
** EXPERIMENTAL
4313
**
4408
**
4314
** ^These routines are used to register a new [virtual table module] name.
4409
** ^These routines are used to register a new [virtual table module] name.
4315
** ^Module names must be registered before
4410
** ^Module names must be registered before
4316
** creating a new [virtual table] using the module and before using a
4411
** creating a new [virtual table] using the module and before using a
4317
** preexisting [virtual table] for the module.
4412
** preexisting [virtual table] for the module.
...
...
4329
** invoke the destructor function (if it is not NULL) when SQLite
4424
** invoke the destructor function (if it is not NULL) when SQLite
4330
** no longer needs the pClientData pointer.  ^The sqlite3_create_module()
4425
** no longer needs the pClientData pointer.  ^The sqlite3_create_module()
4331
** interface is equivalent to sqlite3_create_module_v2() with a NULL
4426
** interface is equivalent to sqlite3_create_module_v2() with a NULL
4332
** destructor.
4427
** destructor.
4333
*/
4428
*/
4334
SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_create_module(
4429
SQLITE_API int sqlite3_create_module(
4335
  sqlite3 *db,               /* SQLite connection to register module with */
4430
  sqlite3 *db,               /* SQLite connection to register module with */
4336
  const char *zName,         /* Name of the module */
4431
  const char *zName,         /* Name of the module */
4337
  const sqlite3_module *p,   /* Methods for the module */
4432
  const sqlite3_module *p,   /* Methods for the module */
4338
  void *pClientData          /* Client data for xCreate/xConnect */
4433
  void *pClientData          /* Client data for xCreate/xConnect */
4339
);
4434
);
4340
SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_create_module_v2(
4435
SQLITE_API int sqlite3_create_module_v2(
4341
  sqlite3 *db,               /* SQLite connection to register module with */
4436
  sqlite3 *db,               /* SQLite connection to register module with */
4342
  const char *zName,         /* Name of the module */
4437
  const char *zName,         /* Name of the module */
4343
  const sqlite3_module *p,   /* Methods for the module */
4438
  const sqlite3_module *p,   /* Methods for the module */
4344
  void *pClientData,         /* Client data for xCreate/xConnect */
4439
  void *pClientData,         /* Client data for xCreate/xConnect */
4345
  void(*xDestroy)(void*)     /* Module destructor function */
4440
  void(*xDestroy)(void*)     /* Module destructor function */
4346
);
4441
);
4347
4442
4348
/*
4443
/*
4349
** CAPI3REF: Virtual Table Instance Object
4444
** CAPI3REF: Virtual Table Instance Object
4350
** KEYWORDS: sqlite3_vtab
4445
** KEYWORDS: sqlite3_vtab
4351
** EXPERIMENTAL
4352
**
4446
**
4353
** Every [virtual table module] implementation uses a subclass
4447
** Every [virtual table module] implementation uses a subclass
4354
** of this object to describe a particular instance
4448
** of this object to describe a particular instance
4355
** of the [virtual table].  Each subclass will
4449
** of the [virtual table].  Each subclass will
4356
** be tailored to the specific needs of the module implementation.
4450
** be tailored to the specific needs of the module implementation.
...
...
4372
};
4466
};
4373
4467
4374
/*
4468
/*
4375
** CAPI3REF: Virtual Table Cursor Object
4469
** CAPI3REF: Virtual Table Cursor Object
4376
** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor}
4470
** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor}
4377
** EXPERIMENTAL
4378
**
4471
**
4379
** Every [virtual table module] implementation uses a subclass of the
4472
** Every [virtual table module] implementation uses a subclass of the
4380
** following structure to describe cursors that point into the
4473
** following structure to describe cursors that point into the
4381
** [virtual table] and are used
4474
** [virtual table] and are used
4382
** to loop through the virtual table.  Cursors are created using the
4475
** to loop through the virtual table.  Cursors are created using the
...
...
4394
  /* Virtual table implementations will typically add additional fields */
4487
  /* Virtual table implementations will typically add additional fields */
4395
};
4488
};
4396
4489
4397
/*
4490
/*
4398
** CAPI3REF: Declare The Schema Of A Virtual Table
4491
** CAPI3REF: Declare The Schema Of A Virtual Table
4399
** EXPERIMENTAL
4400
**
4492
**
4401
** ^The [xCreate] and [xConnect] methods of a
4493
** ^The [xCreate] and [xConnect] methods of a
4402
** [virtual table module] call this interface
4494
** [virtual table module] call this interface
4403
** to declare the format (the names and datatypes of the columns) of
4495
** to declare the format (the names and datatypes of the columns) of
4404
** the virtual tables they implement.
4496
** the virtual tables they implement.
4405
*/
4497
*/
4406
SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
4498
SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
4407
4499
4408
/*
4500
/*
4409
** CAPI3REF: Overload A Function For A Virtual Table
4501
** CAPI3REF: Overload A Function For A Virtual Table
4410
** EXPERIMENTAL
4411
**
4502
**
4412
** ^(Virtual tables can provide alternative implementations of functions
4503
** ^(Virtual tables can provide alternative implementations of functions
4413
** using the [xFindFunction] method of the [virtual table module].  
4504
** using the [xFindFunction] method of the [virtual table module].  
4414
** But global versions of those functions
4505
** But global versions of those functions
4415
** must exist in order to be overloaded.)^
4506
** must exist in order to be overloaded.)^
...
...
4420
** of the new function always causes an exception to be thrown.  So
4511
** of the new function always causes an exception to be thrown.  So
4421
** the new function is not good for anything by itself.  Its only
4512
** the new function is not good for anything by itself.  Its only
4422
** purpose is to be a placeholder function that can be overloaded
4513
** purpose is to be a placeholder function that can be overloaded
4423
** by a [virtual table].
4514
** by a [virtual table].
4424
*/
4515
*/
4425
SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
4516
SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
4426
4517
4427
/*
4518
/*
4428
** The interface to the virtual-table mechanism defined above (back up
4519
** The interface to the virtual-table mechanism defined above (back up
4429
** to a comment remarkably similar to this one) is currently considered
4520
** to a comment remarkably similar to this one) is currently considered
4430
** to be experimental.  The interface might change in incompatible ways.
4521
** to be experimental.  The interface might change in incompatible ways.
4431
** If this is a problem for you, do not use the interface at this time.
4522
** If this is a problem for you, do not use the interface at this time.
4432
**
4523
**
4433
** When the virtual-table mechanism stabilizes, we will declare the
4524
** When the virtual-table mechanism stabilizes, we will declare the
4434
** interface fixed, support it indefinitely, and remove this comment.
4525
** interface fixed, support it indefinitely, and remove this comment.
4435
**
4436
****** EXPERIMENTAL - subject to change without notice **************
4437
*/
4526
*/
4438
4527
4439
/*
4528
/*
4440
** CAPI3REF: A Handle To An Open BLOB
4529
** CAPI3REF: A Handle To An Open BLOB
4441
** KEYWORDS: {BLOB handle} {BLOB handles}
4530
** KEYWORDS: {BLOB handle} {BLOB handles}
...
...
4774
SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*);
4863
SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*);
4775
SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
4864
SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
4776
4865
4777
/*
4866
/*
4778
** CAPI3REF: Mutex Methods Object
4867
** CAPI3REF: Mutex Methods Object
4779
** EXPERIMENTAL
4780
**
4868
**
4781
** An instance of this structure defines the low-level routines
4869
** An instance of this structure defines the low-level routines
4782
** used to allocate and use mutexes.
4870
** used to allocate and use mutexes.
4783
**
4871
**
4784
** Usually, the default mutex implementations provided by SQLite are
4872
** Usually, the default mutex implementations provided by SQLite are
...
...
4987
#define SQLITE_TESTCTRL_ASSERT                  12
5075
#define SQLITE_TESTCTRL_ASSERT                  12
4988
#define SQLITE_TESTCTRL_ALWAYS                  13
5076
#define SQLITE_TESTCTRL_ALWAYS                  13
4989
#define SQLITE_TESTCTRL_RESERVE                 14
5077
#define SQLITE_TESTCTRL_RESERVE                 14
4990
#define SQLITE_TESTCTRL_OPTIMIZATIONS           15
5078
#define SQLITE_TESTCTRL_OPTIMIZATIONS           15
4991
#define SQLITE_TESTCTRL_ISKEYWORD               16
5079
#define SQLITE_TESTCTRL_ISKEYWORD               16
5080
#define SQLITE_TESTCTRL_PGHDRSZ                 17
4992
#define SQLITE_TESTCTRL_LAST                    16
5081
#define SQLITE_TESTCTRL_LAST                    17
4993
5082
4994
/*
5083
/*
4995
** CAPI3REF: SQLite Runtime Status
5084
** CAPI3REF: SQLite Runtime Status
4996
** EXPERIMENTAL
4997
**
5085
**
4998
** ^This interface is used to retrieve runtime status information
5086
** ^This interface is used to retrieve runtime status information
4999
** about the preformance of SQLite, and optionally to reset various
5087
** about the preformance of SQLite, and optionally to reset various
5000
** highwater marks.  ^The first argument is an integer code for
5088
** highwater marks.  ^The first argument is an integer code for
5001
** the specific parameter to measure.  ^(Recognized integer codes
5089
** the specific parameter to measure.  ^(Recognized integer codes
...
...
5019
** and it is possible that another thread might change the parameter
5107
** and it is possible that another thread might change the parameter
5020
** in between the times when *pCurrent and *pHighwater are written.
5108
** in between the times when *pCurrent and *pHighwater are written.
5021
**
5109
**
5022
** See also: [sqlite3_db_status()]
5110
** See also: [sqlite3_db_status()]
5023
*/
5111
*/
5024
SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
5112
SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
5025
5113
5026
5114
5027
/*
5115
/*
5028
** CAPI3REF: Status Parameters
5116
** CAPI3REF: Status Parameters
5029
** EXPERIMENTAL
5030
**
5117
**
5031
** These integer constants designate various run-time status parameters
5118
** These integer constants designate various run-time status parameters
5032
** that can be returned by [sqlite3_status()].
5119
** that can be returned by [sqlite3_status()].
5033
**
5120
**
5034
** <dl>
5121
** <dl>
...
...
5111
#define SQLITE_STATUS_PAGECACHE_SIZE       7
5198
#define SQLITE_STATUS_PAGECACHE_SIZE       7
5112
#define SQLITE_STATUS_SCRATCH_SIZE         8
5199
#define SQLITE_STATUS_SCRATCH_SIZE         8
5113
5200
5114
/*
5201
/*
5115
** CAPI3REF: Database Connection Status
5202
** CAPI3REF: Database Connection Status
5116
** EXPERIMENTAL
5117
**
5203
**
5118
** ^This interface is used to retrieve runtime status information 
5204
** ^This interface is used to retrieve runtime status information 
5119
** about a single [database connection].  ^The first argument is the
5205
** about a single [database connection].  ^The first argument is the
5120
** database connection object to be interrogated.  ^The second argument
5206
** database connection object to be interrogated.  ^The second argument
5121
** is the parameter to interrogate.  ^Currently, the only allowed value
5207
** is an integer constant, taken from the set of
5122
** for the second parameter is [SQLITE_DBSTATUS_LOOKASIDE_USED].
5208
** [SQLITE_DBSTATUS_LOOKASIDE_USED | SQLITE_DBSTATUS_*] macros, that
5123
** Additional options will likely appear in future releases of SQLite.
5209
** determiness the parameter to interrogate.  The set of 
5210
** [SQLITE_DBSTATUS_LOOKASIDE_USED | SQLITE_DBSTATUS_*] macros is likely
5211
** to grow in future releases of SQLite.
5124
**
5212
**
5125
** ^The current value of the requested parameter is written into *pCur
5213
** ^The current value of the requested parameter is written into *pCur
5126
** and the highest instantaneous value is written into *pHiwtr.  ^If
5214
** and the highest instantaneous value is written into *pHiwtr.  ^If
5127
** the resetFlg is true, then the highest instantaneous value is
5215
** the resetFlg is true, then the highest instantaneous value is
5128
** reset back down to the current value.
5216
** reset back down to the current value.
5129
**
5217
**
5130
** See also: [sqlite3_status()] and [sqlite3_stmt_status()].
5218
** See also: [sqlite3_status()] and [sqlite3_stmt_status()].
5131
*/
5219
*/
5132
SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
5220
SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
5133
5221
5134
/*
5222
/*
5135
** CAPI3REF: Status Parameters for database connections
5223
** CAPI3REF: Status Parameters for database connections
5136
** EXPERIMENTAL
5137
**
5224
**
5138
** These constants are the available integer "verbs" that can be passed as
5225
** These constants are the available integer "verbs" that can be passed as
5139
** the second argument to the [sqlite3_db_status()] interface.
5226
** the second argument to the [sqlite3_db_status()] interface.
5140
**
5227
**
5141
** New verbs may be added in future releases of SQLite. Existing verbs
5228
** New verbs may be added in future releases of SQLite. Existing verbs
...
...
5146
**
5233
**
5147
** <dl>
5234
** <dl>
5148
** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
5235
** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
5149
** <dd>This parameter returns the number of lookaside memory slots currently
5236
** <dd>This parameter returns the number of lookaside memory slots currently
5150
** checked out.</dd>)^
5237
** checked out.</dd>)^
5238
**
5239
** <dt>SQLITE_DBSTATUS_CACHE_USED</dt>
5240
** <dd>^This parameter returns the approximate number of of bytes of heap
5241
** memory used by all pager caches associated with the database connection.
5242
** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.
5243
** </dd>
5151
** </dl>
5244
** </dl>
5152
*/
5245
*/
5153
#define SQLITE_DBSTATUS_LOOKASIDE_USED     0
5246
#define SQLITE_DBSTATUS_LOOKASIDE_USED     0
5247
#define SQLITE_DBSTATUS_CACHE_USED         1
5248
#define SQLITE_DBSTATUS_MAX                1   /* Largest defined DBSTATUS */
5154
5249
5155
5250
5156
/*
5251
/*
5157
** CAPI3REF: Prepared Statement Status
5252
** CAPI3REF: Prepared Statement Status
5158
** EXPERIMENTAL
5159
**
5253
**
5160
** ^(Each prepared statement maintains various
5254
** ^(Each prepared statement maintains various
5161
** [SQLITE_STMTSTATUS_SORT | counters] that measure the number
5255
** [SQLITE_STMTSTATUS_SORT | counters] that measure the number
5162
** of times it has performed specific operations.)^  These counters can
5256
** of times it has performed specific operations.)^  These counters can
5163
** be used to monitor the performance characteristics of the prepared
5257
** be used to monitor the performance characteristics of the prepared
...
...
5175
** ^If the resetFlg is true, then the counter is reset to zero after this
5269
** ^If the resetFlg is true, then the counter is reset to zero after this
5176
** interface call returns.
5270
** interface call returns.
5177
**
5271
**
5178
** See also: [sqlite3_status()] and [sqlite3_db_status()].
5272
** See also: [sqlite3_status()] and [sqlite3_db_status()].
5179
*/
5273
*/
5180
SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
5274
SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
5181
5275
5182
/*
5276
/*
5183
** CAPI3REF: Status Parameters for prepared statements
5277
** CAPI3REF: Status Parameters for prepared statements
5184
** EXPERIMENTAL
5185
**
5278
**
5186
** These preprocessor macros define integer codes that name counter
5279
** These preprocessor macros define integer codes that name counter
5187
** values associated with the [sqlite3_stmt_status()] interface.
5280
** values associated with the [sqlite3_stmt_status()] interface.
5188
** The meanings of the various counters are as follows:
5281
** The meanings of the various counters are as follows:
5189
**
5282
**
...
...
5197
** <dt>SQLITE_STMTSTATUS_SORT</dt>
5290
** <dt>SQLITE_STMTSTATUS_SORT</dt>
5198
** <dd>^This is the number of sort operations that have occurred.
5291
** <dd>^This is the number of sort operations that have occurred.
5199
** A non-zero value in this counter may indicate an opportunity to
5292
** A non-zero value in this counter may indicate an opportunity to
5200
** improvement performance through careful use of indices.</dd>
5293
** improvement performance through careful use of indices.</dd>
5201
**
5294
**
5295
** <dt>SQLITE_STMTSTATUS_AUTOINDEX</dt>
5296
** <dd>^This is the number of rows inserted into transient indices that
5297
** were created automatically in order to help joins run faster.
5298
** A non-zero value in this counter may indicate an opportunity to
5299
** improvement performance by adding permanent indices that do not
5300
** need to be reinitialized each time the statement is run.</dd>
5301
**
5202
** </dl>
5302
** </dl>
5203
*/
5303
*/
5204
#define SQLITE_STMTSTATUS_FULLSCAN_STEP     1
5304
#define SQLITE_STMTSTATUS_FULLSCAN_STEP     1
5205
#define SQLITE_STMTSTATUS_SORT              2
5305
#define SQLITE_STMTSTATUS_SORT              2
5306
#define SQLITE_STMTSTATUS_AUTOINDEX         3
5206
5307
5207
/*
5308
/*
5208
** CAPI3REF: Custom Page Cache Object
5309
** CAPI3REF: Custom Page Cache Object
5209
** EXPERIMENTAL
5210
**
5310
**
5211
** The sqlite3_pcache type is opaque.  It is implemented by
5311
** The sqlite3_pcache type is opaque.  It is implemented by
5212
** the pluggable module.  The SQLite core has no knowledge of
5312
** the pluggable module.  The SQLite core has no knowledge of
5213
** its size or internal structure and never deals with the
5313
** its size or internal structure and never deals with the
5214
** sqlite3_pcache object except by holding and passing pointers
5314
** sqlite3_pcache object except by holding and passing pointers
...
...
5219
typedef struct sqlite3_pcache sqlite3_pcache;
5319
typedef struct sqlite3_pcache sqlite3_pcache;
5220
5320
5221
/*
5321
/*
5222
** CAPI3REF: Application Defined Page Cache.
5322
** CAPI3REF: Application Defined Page Cache.
5223
** KEYWORDS: {page cache}
5323
** KEYWORDS: {page cache}
5224
** EXPERIMENTAL
5225
**
5324
**
5226
** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can
5325
** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can
5227
** register an alternative page cache implementation by passing in an 
5326
** register an alternative page cache implementation by passing in an 
5228
** instance of the sqlite3_pcache_methods structure.)^ The majority of the 
5327
** instance of the sqlite3_pcache_methods structure.)^ The majority of the 
5229
** heap memory used by SQLite is used by the page cache to cache data read 
5328
** heap memory used by SQLite is used by the page cache to cache data read 
...
...
5361
  void (*xDestroy)(sqlite3_pcache*);
5460
  void (*xDestroy)(sqlite3_pcache*);
5362
};
5461
};
5363
5462
5364
/*
5463
/*
5365
** CAPI3REF: Online Backup Object
5464
** CAPI3REF: Online Backup Object
5366
** EXPERIMENTAL
5367
**
5465
**
5368
** The sqlite3_backup object records state information about an ongoing
5466
** The sqlite3_backup object records state information about an ongoing
5369
** online backup operation.  ^The sqlite3_backup object is created by
5467
** online backup operation.  ^The sqlite3_backup object is created by
5370
** a call to [sqlite3_backup_init()] and is destroyed by a call to
5468
** a call to [sqlite3_backup_init()] and is destroyed by a call to
5371
** [sqlite3_backup_finish()].
5469
** [sqlite3_backup_finish()].
...
...
5374
*/
5472
*/
5375
typedef struct sqlite3_backup sqlite3_backup;
5473
typedef struct sqlite3_backup sqlite3_backup;
5376
5474
5377
/*
5475
/*
5378
** CAPI3REF: Online Backup API.
5476
** CAPI3REF: Online Backup API.
5379
** EXPERIMENTAL
5380
**
5477
**
5381
** The backup API copies the content of one database into another.
5478
** The backup API copies the content of one database into another.
5382
** It is useful either for creating backups of databases or
5479
** It is useful either for creating backups of databases or
5383
** for copying in-memory databases to or from persistent files. 
5480
** for copying in-memory databases to or from persistent files. 
5384
**
5481
**
...
...
5443
** then an [error code] is returned. ^As well as [SQLITE_OK] and
5540
** then an [error code] is returned. ^As well as [SQLITE_OK] and
5444
** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
5541
** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
5445
** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
5542
** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
5446
** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
5543
** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
5447
**
5544
**
5448
** ^The sqlite3_backup_step() might return [SQLITE_READONLY] if the destination
5545
** ^(The sqlite3_backup_step() might return [SQLITE_READONLY] if
5449
** database was opened read-only or if
5546
** <ol>
5450
** the destination is an in-memory database with a different page size
5547
** <li> the destination database was opened read-only, or
5451
** from the source database.
5548
** <li> the destination database is using write-ahead-log journaling
5549
** and the destination and source page sizes differ, or
5550
** <li> The destination database is an in-memory database and the
5551
** destination and source page sizes differ.
5552
** </ol>)^
5452
**
5553
**
5453
** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
5554
** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
5454
** the [sqlite3_busy_handler | busy-handler function]
5555
** the [sqlite3_busy_handler | busy-handler function]
5455
** is invoked (if one is specified). ^If the 
5556
** is invoked (if one is specified). ^If the 
5456
** busy-handler returns non-zero before the lock is available, then 
5557
** busy-handler returns non-zero before the lock is available, then 
...
...
5562
SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
5663
SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
5563
SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
5664
SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
5564
5665
5565
/*
5666
/*
5566
** CAPI3REF: Unlock Notification
5667
** CAPI3REF: Unlock Notification
5567
** EXPERIMENTAL
5568
**
5668
**
5569
** ^When running in shared-cache mode, a database operation may fail with
5669
** ^When running in shared-cache mode, a database operation may fail with
5570
** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
5670
** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
5571
** individual tables within the shared-cache cannot be obtained. See
5671
** individual tables within the shared-cache cannot be obtained. See
5572
** [SQLite Shared-Cache Mode] for a description of shared-cache locking. 
5672
** [SQLite Shared-Cache Mode] for a description of shared-cache locking. 
...
...
5684
);
5784
);
5685
5785
5686
5786
5687
/*
5787
/*
5688
** CAPI3REF: String Comparison
5788
** CAPI3REF: String Comparison
5689
** EXPERIMENTAL
5690
**
5789
**
5691
** ^The [sqlite3_strnicmp()] API allows applications and extensions to
5790
** ^The [sqlite3_strnicmp()] API allows applications and extensions to
5692
** compare the contents of two buffers containing UTF-8 strings in a
5791
** compare the contents of two buffers containing UTF-8 strings in a
5693
** case-indendent fashion, using the same definition of case independence 
5792
** case-indendent fashion, using the same definition of case independence 
5694
** that SQLite uses internally when comparing identifiers.
5793
** that SQLite uses internally when comparing identifiers.
5695
*/
5794
*/
5696
SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
5795
SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
5697
5796
5698
/*
5797
/*
5699
** CAPI3REF: Error Logging Interface
5798
** CAPI3REF: Error Logging Interface
5700
** EXPERIMENTAL
5701
**
5799
**
5702
** ^The [sqlite3_log()] interface writes a message into the error log
5800
** ^The [sqlite3_log()] interface writes a message into the error log
5703
** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()].
5801
** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()].
5704
** ^If logging is enabled, the zFormat string and subsequent arguments are
5802
** ^If logging is enabled, the zFormat string and subsequent arguments are
5705
** passed through to [sqlite3_vmprintf()] to generate the final output string.
5803
** used with [sqlite3_snprintf()] to generate the final output string.
5706
**
5804
**
5707
** The sqlite3_log() interface is intended for use by extensions such as
5805
** The sqlite3_log() interface is intended for use by extensions such as
5708
** virtual tables, collating functions, and SQL functions.  While there is
5806
** virtual tables, collating functions, and SQL functions.  While there is
5709
** nothing to prevent an application from calling sqlite3_log(), doing so
5807
** nothing to prevent an application from calling sqlite3_log(), doing so
5710
** is considered bad form.
5808
** is considered bad form.
...
...
5718
** buffer.
5816
** buffer.
5719
*/
5817
*/
5720
SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
5818
SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
5721
5819
5722
/*
5820
/*
5821
** CAPI3REF: Write-Ahead Log Commit Hook
5822
**
5823
** ^The [sqlite3_wal_hook()] function is used to register a callback that
5824
** will be invoked each time a database connection commits data to a
5825
** [write-ahead log] (i.e. whenever a transaction is committed in
5826
** [journal_mode | journal_mode=WAL mode]). 
5827
**
5828
** ^The callback is invoked by SQLite after the commit has taken place and 
5829
** the associated write-lock on the database released, so the implementation 
5830
** may read, write or [checkpoint] the database as required.
5831
**
5832
** ^The first parameter passed to the callback function when it is invoked
5833
** is a copy of the third parameter passed to sqlite3_wal_hook() when
5834
** registering the callback. ^The second is a copy of the database handle.
5835
** ^The third parameter is the name of the database that was written to -
5836
** either "main" or the name of an [ATTACH]-ed database. ^The fourth parameter
5837
** is the number of pages currently in the write-ahead log file,
5838
** including those that were just committed.
5839
**
5840
** The callback function should normally return [SQLITE_OK].  ^If an error
5841
** code is returned, that error will propagate back up through the
5842
** SQLite code base to cause the statement that provoked the callback
5843
** to report an error, though the commit will have still occurred. If the
5844
** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value
5845
** that does not correspond to any valid SQLite error code, the results
5846
** are undefined.
5847
**
5848
** A single database handle may have at most a single write-ahead log callback 
5849
** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any
5850
** previously registered write-ahead log callback. ^Note that the
5851
** [sqlite3_wal_autocheckpoint()] interface and the
5852
** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will
5853
** those overwrite any prior [sqlite3_wal_hook()] settings.
5854
*/
5855
SQLITE_API void *sqlite3_wal_hook(
5856
  sqlite3*, 
5857
  int(*)(void *,sqlite3*,const char*,int),
5858
  void*
5859
);
5860
5861
/*
5862
** CAPI3REF: Configure an auto-checkpoint
5863
**
5864
** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around
5865
** [sqlite3_wal_hook()] that causes any database on [database connection] D
5866
** to automatically [checkpoint]
5867
** after committing a transaction if there are N or
5868
** more frames in the [write-ahead log] file.  ^Passing zero or 
5869
** a negative value as the nFrame parameter disables automatic
5870
** checkpoints entirely.
5871
**
5872
** ^The callback registered by this function replaces any existing callback
5873
** registered using [sqlite3_wal_hook()].  ^Likewise, registering a callback
5874
** using [sqlite3_wal_hook()] disables the automatic checkpoint mechanism
5875
** configured by this function.
5876
**
5877
** ^The [wal_autocheckpoint pragma] can be used to invoke this interface
5878
** from SQL.
5879
**
5880
** ^Every new [database connection] defaults to having the auto-checkpoint
5881
** enabled with a threshold of 1000 pages.  The use of this interface
5882
** is only necessary if the default setting is found to be suboptimal
5883
** for a particular application.
5884
*/
5885
SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
5886
5887
/*
5888
** CAPI3REF: Checkpoint a database
5889
**
5890
** ^The [sqlite3_wal_checkpoint(D,X)] interface causes database named X
5891
** on [database connection] D to be [checkpointed].  ^If X is NULL or an
5892
** empty string, then a checkpoint is run on all databases of
5893
** connection D.  ^If the database connection D is not in
5894
** [WAL | write-ahead log mode] then this interface is a harmless no-op.
5895
**
5896
** ^The [wal_checkpoint pragma] can be used to invoke this interface
5897
** from SQL.  ^The [sqlite3_wal_autocheckpoint()] interface and the
5898
** [wal_autocheckpoint pragma] can be used to cause this interface to be
5899
** run whenever the WAL reaches a certain size threshold.
5900
*/
5901
SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
5902
5903
/*
5723
** Undo the hack that converts floating point types to integer for
5904
** Undo the hack that converts floating point types to integer for
5724
** builds on processors without floating point support.
5905
** builds on processors without floating point support.
5725
*/
5906
*/
5726
#ifdef SQLITE_OMIT_FLOATING_POINT
5907
#ifdef SQLITE_OMIT_FLOATING_POINT
5727
# undef double
5908
# undef double