BathyScapheのSQLiteデータベース内を覗くアプリ
Révision | a7f8765a8cfcdc1edb87213da164572eeee9a9f9 (tree) |
---|---|
l'heure | 2011-12-03 00:25:11 |
Auteur | masakih <masakih@user...> |
Commiter | masakih |
Xcode4に以降 Objective-C 2.0導入 Database version 4(Favorites table) に対応。
git-svn-id: svn+ssh://macmini/usr/local/svnrepos/BSDBViewer/BSDBViewer@17 477addb1-df5c-4826-a637-c2b1bdcd60d4
@@ -8,6 +8,7 @@ | ||
8 | 8 | |
9 | 9 | NSArray *boards; |
10 | 10 | } |
11 | +@property BOOL excludeNotHasReadThread; | |
11 | 12 | |
12 | 13 | - (id)boardIDAtRow:(unsigned int)row; |
13 | 14 | - (NSArray *)boardIDsInSet:(NSIndexSet *)set; |
@@ -3,6 +3,7 @@ | ||
3 | 3 | #import "BSDBViewer.h" |
4 | 4 | |
5 | 5 | @implementation BSDBBoardSource |
6 | +@synthesize excludeNotHasReadThread; | |
6 | 7 | |
7 | 8 | - (void)dealloc |
8 | 9 | { |
@@ -8,14 +8,14 @@ | ||
8 | 8 | NSNumber *boardID; |
9 | 9 | } |
10 | 10 | |
11 | +@property (retain) NSArray *threads; | |
12 | +@property (retain) NSNumber *boardID; | |
13 | + | |
11 | 14 | - (id)threadIDAtRow:(unsigned int)row; |
12 | 15 | - (NSArray *)threadIDsInSet:(NSIndexSet *)set; |
13 | 16 | |
14 | 17 | - (IBAction)update:(id)sender; |
15 | 18 | |
16 | -- (void)setBoardID:(NSNumber *)boardID; | |
17 | -- (NSNumber *)boardID; | |
18 | - | |
19 | 19 | @end |
20 | 20 | |
21 | 21 | @interface NSObject (BSDBThreadSourceDelegate) |
@@ -4,6 +4,10 @@ | ||
4 | 4 | |
5 | 5 | @implementation BSDBThreadSource |
6 | 6 | |
7 | +@synthesize threads; | |
8 | +@synthesize boardID; | |
9 | + | |
10 | + | |
7 | 11 | - (void)dealloc |
8 | 12 | { |
9 | 13 | [threads release]; |
@@ -34,21 +38,6 @@ | ||
34 | 38 | return delegate; |
35 | 39 | } |
36 | 40 | |
37 | -- (void)setThreads:(NSArray *)array | |
38 | -{ | |
39 | - @synchronized(self) { | |
40 | - [threads autorelease]; | |
41 | - threads = [array retain]; | |
42 | - } | |
43 | -} | |
44 | -- (NSArray *)threads | |
45 | -{ | |
46 | - id result = nil; | |
47 | - @synchronized(self) { | |
48 | - result = [threads retain]; | |
49 | - } | |
50 | - return [result autorelease]; | |
51 | -} | |
52 | 41 | - (void)setBoardID:(NSNumber *)newBoardID |
53 | 42 | { |
54 | 43 | if([boardID isEqual:newBoardID]) return; |
@@ -65,19 +54,11 @@ | ||
65 | 54 | |
66 | 55 | - (id)threadIDAtRow:(unsigned int)row |
67 | 56 | { |
68 | - id result = nil; | |
69 | - @synchronized(self) { | |
70 | - result = [[threads objectAtIndex:row] retain]; | |
71 | - } | |
72 | - return [result autorelease]; | |
57 | + return [self.threads objectAtIndex:row]; | |
73 | 58 | } |
74 | 59 | - (NSArray *)threadIDsInSet:(NSIndexSet *)set |
75 | 60 | { |
76 | - NSArray *result = nil; | |
77 | - @synchronized(self) { | |
78 | - result = [threads objectsAtIndexes:set]; | |
79 | - } | |
80 | - return result; | |
61 | + return [self.threads objectsAtIndexes:set]; | |
81 | 62 | } |
82 | 63 | |
83 | 64 | /* |
@@ -94,6 +75,13 @@ | ||
94 | 75 | isDatOchi INTEGER NOT NULL DEFAULT 0 CHECK(isDatOchi IN (0,1)), |
95 | 76 | IsFavorite INTEGER NOT NULL DEFAULT 0 CHECK(IsFavorite IN (0,1))) |
96 | 77 | */ |
78 | +/* | |
79 | + SELECT * , | |
80 | + (SELECT count(*) FROM Favorites | |
81 | + WHERE BoardID = BoardThreadInfoView.BoardID | |
82 | + AND ThreadID = BoardThreadInfoView.ThreadID) AS isFavorite | |
83 | + FROM BoardThreadInfoView; | |
84 | + */ | |
97 | 85 | - (IBAction)update:(id)sender |
98 | 86 | { |
99 | 87 | if(!boardID) return; |
@@ -109,9 +97,12 @@ | ||
109 | 97 | NSString *query = [NSString stringWithFormat: |
110 | 98 | @"SELECT threadname, threadid, numberOfAll, numberOfRead," |
111 | 99 | @"modifiedDate, lastWrittenDate," |
112 | - @"isDatOchi,IsFavorite " | |
113 | - @"FROM %@ WHERE boardid = %@", | |
114 | - @"ThreadInfo",[self boardID]]; | |
100 | + @"isDatOchi" | |
101 | + @", (SELECT count(*) FROM Favorites " | |
102 | + @" WHERE BoardID = BoardThreadInfoView.BoardID " | |
103 | + @" AND ThreadID = BoardThreadInfoView.ThreadID) AS isFavorite " | |
104 | + @" FROM %@ WHERE boardid = %@ ", | |
105 | + @"BoardThreadInfoView",[self boardID]]; | |
115 | 106 | |
116 | 107 | id cursor = [db cursorForSQL:query]; |
117 | 108 | if([db lastErrorID] != 0) { |
@@ -23,6 +23,15 @@ | ||
23 | 23 | - (IBAction)deleteThreadInfo:(id)sender; |
24 | 24 | - (IBAction)showThreadInfo:(id)sender; |
25 | 25 | |
26 | +@property (retain) id window; | |
27 | +@property (retain) id boardArrayController; | |
28 | +@property (retain) id boardSource; | |
29 | +@property (retain) id boardView; | |
30 | +@property (retain) id threadArrayController; | |
31 | +@property (retain) id threadSource; | |
32 | +@property (retain) id threadView; | |
33 | +@property int progressStack; | |
34 | +@property (retain) NSMutableDictionary *boardNameCache; | |
26 | 35 | @end |
27 | 36 | |
28 | 37 | @interface BSDBDateTransformer : NSValueTransformer |
@@ -9,6 +9,16 @@ | ||
9 | 9 | static NSString *const BSDBViewerSQLiteDBKey = @"BSDBViewerSQLiteDBKey"; |
10 | 10 | static NSString *const InProgressKey = @"inProgress"; |
11 | 11 | |
12 | +@synthesize window; | |
13 | +@synthesize boardArrayController; | |
14 | +@synthesize boardSource; | |
15 | +@synthesize boardView; | |
16 | +@synthesize threadArrayController; | |
17 | +@synthesize threadSource; | |
18 | +@synthesize threadView; | |
19 | +@synthesize progressStack; | |
20 | +@synthesize boardNameCache; | |
21 | + | |
12 | 22 | - (void)dealloc |
13 | 23 | { |
14 | 24 | [boardNameCache release]; |
@@ -103,7 +113,7 @@ final: | ||
103 | 113 | { |
104 | 114 | id res = [self BSSupportFolder]; |
105 | 115 | |
106 | - res = [res stringByAppendingPathComponent:@"BathyScaphe.db"]; | |
116 | + res = [res stringByAppendingPathComponent:@"BathyScaphe.db.new"]; | |
107 | 117 | |
108 | 118 | return resolveAlias(res); |
109 | 119 | } |
@@ -221,11 +231,10 @@ final: | ||
221 | 231 | |
222 | 232 | - (void)openThreadsInBS:(NSArray *)infos |
223 | 233 | { |
224 | - id enume = [infos objectEnumerator]; | |
225 | 234 | id obj; |
226 | 235 | id targetBoardID = [threadSource boardID]; |
227 | 236 | |
228 | - while(obj = [enume nextObject]) { | |
237 | + for(obj in infos) { | |
229 | 238 | id threadID = [obj objectForKey:@"threadid"]; |
230 | 239 | if(!threadID) continue; |
231 | 240 | [self openInBSThreadID:threadID boardID:targetBoardID]; |
@@ -243,13 +252,12 @@ final: | ||
243 | 252 | SQLiteDB *db = [self sqliteDB]; |
244 | 253 | SQLiteReservedQuery *deleQ = [db reservedQuery:query]; |
245 | 254 | |
246 | - id enume = [infos objectEnumerator]; | |
247 | 255 | id obj; |
248 | 256 | id targetBoardID = [threadSource boardID]; |
249 | 257 | |
250 | 258 | [self incrementProgressStack]; |
251 | 259 | [db beginTransaction]; |
252 | - while(obj = [enume nextObject]) { | |
260 | + for(obj in infos) { | |
253 | 261 | id info = [obj objectForKey:@"threadid"]; |
254 | 262 | if(!info) continue; |
255 | 263 | NSArray *values = [NSArray arrayWithObjects: |
@@ -3,7 +3,7 @@ | ||
3 | 3 | archiveVersion = 1; |
4 | 4 | classes = { |
5 | 5 | }; |
6 | - objectVersion = 44; | |
6 | + objectVersion = 46; | |
7 | 7 | objects = { |
8 | 8 | |
9 | 9 | /* Begin PBXBuildFile section */ |
@@ -187,9 +187,16 @@ | ||
187 | 187 | /* Begin PBXProject section */ |
188 | 188 | 29B97313FDCFA39411CA2CEA /* Project object */ = { |
189 | 189 | isa = PBXProject; |
190 | + attributes = { | |
191 | + LastUpgradeCheck = 0420; | |
192 | + }; | |
190 | 193 | buildConfigurationList = C01FCF4E08A954540054247B /* Build configuration list for PBXProject "BSDBViewer" */; |
191 | - compatibilityVersion = "Xcode 3.0"; | |
194 | + compatibilityVersion = "Xcode 3.2"; | |
195 | + developmentRegion = English; | |
192 | 196 | hasScannedForEncodings = 1; |
197 | + knownRegions = ( | |
198 | + en, | |
199 | + ); | |
193 | 200 | mainGroup = 29B97314FDCFA39411CA2CEA /* BSDBViewer */; |
194 | 201 | projectDirPath = ""; |
195 | 202 | projectRoot = ""; |
@@ -251,7 +258,6 @@ | ||
251 | 258 | buildSettings = { |
252 | 259 | COPY_PHASE_STRIP = NO; |
253 | 260 | GCC_DYNAMIC_NO_PIC = NO; |
254 | - GCC_ENABLE_FIX_AND_CONTINUE = YES; | |
255 | 261 | GCC_MODEL_TUNING = ""; |
256 | 262 | GCC_OPTIMIZATION_LEVEL = 0; |
257 | 263 | GCC_PRECOMPILE_PREFIX_HEADER = YES; |
@@ -262,7 +268,7 @@ | ||
262 | 268 | "$(inherited)", |
263 | 269 | "\"$(SRCROOT)\"", |
264 | 270 | ); |
265 | - MACOSX_DEPLOYMENT_TARGET = 10.4; | |
271 | + MACOSX_DEPLOYMENT_TARGET = 10.5; | |
266 | 272 | PRODUCT_NAME = BSDBViewer; |
267 | 273 | WRAPPER_EXTENSION = app; |
268 | 274 | ZERO_LINK = NO; |
@@ -283,7 +289,7 @@ | ||
283 | 289 | "$(inherited)", |
284 | 290 | "\"$(SRCROOT)\"", |
285 | 291 | ); |
286 | - MACOSX_DEPLOYMENT_TARGET = 10.4; | |
292 | + MACOSX_DEPLOYMENT_TARGET = 10.5; | |
287 | 293 | PRODUCT_NAME = BSDBViewer; |
288 | 294 | WRAPPER_EXTENSION = app; |
289 | 295 | ZERO_LINK = NO; |
@@ -293,10 +299,14 @@ | ||
293 | 299 | C01FCF4F08A954540054247B /* Debug */ = { |
294 | 300 | isa = XCBuildConfiguration; |
295 | 301 | buildSettings = { |
302 | + ARCHS = ( | |
303 | + x86_64, | |
304 | + i386, | |
305 | + ); | |
296 | 306 | GCC_WARN_ABOUT_RETURN_TYPE = YES; |
297 | 307 | GCC_WARN_UNUSED_VARIABLE = YES; |
298 | - PREBINDING = NO; | |
299 | - SDKROOT = "$(DEVELOPER_SDK_DIR)/MacOSX10.4u.sdk"; | |
308 | + ONLY_ACTIVE_ARCH = YES; | |
309 | + SDKROOT = macosx10.6; | |
300 | 310 | }; |
301 | 311 | name = Debug; |
302 | 312 | }; |
@@ -304,14 +314,13 @@ | ||
304 | 314 | isa = XCBuildConfiguration; |
305 | 315 | buildSettings = { |
306 | 316 | ARCHS = ( |
307 | - ppc, | |
317 | + x86_64, | |
308 | 318 | i386, |
309 | 319 | ); |
310 | 320 | GCC_PREPROCESSOR_DEFINITIONS = ""; |
311 | 321 | GCC_WARN_ABOUT_RETURN_TYPE = YES; |
312 | 322 | GCC_WARN_UNUSED_VARIABLE = YES; |
313 | - PREBINDING = NO; | |
314 | - SDKROOT = "$(DEVELOPER_SDK_DIR)/MacOSX10.4u.sdk"; | |
323 | + SDKROOT = macosx10.6; | |
315 | 324 | }; |
316 | 325 | name = Release; |
317 | 326 | }; |
@@ -17,9 +17,9 @@ | ||
17 | 17 | ** |
18 | 18 | ** Some of the definitions that are in this file are marked as |
19 | 19 | ** "experimental". Experimental interfaces are normally new |
20 | -** features recently added to SQLite. We do not anticipate changes | |
21 | -** to experimental interfaces but reserve to make minor changes if | |
22 | -** experience from use "in the wild" suggest such changes are prudent. | |
20 | +** features recently added to SQLite. We do not anticipate changes | |
21 | +** to experimental interfaces but reserve the right to make minor changes | |
22 | +** if experience from use "in the wild" suggest such changes are prudent. | |
23 | 23 | ** |
24 | 24 | ** The official C-language API documentation for SQLite is derived |
25 | 25 | ** from comments in this file. This file is the authoritative source |
@@ -29,8 +29,6 @@ | ||
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 | -** | |
33 | -** @(#) $Id: sqlite3.h,v 1.4 2007/08/13 17:49:46 masakih Exp $ | |
34 | 32 | */ |
35 | 33 | #ifndef _SQLITE3_H_ |
36 | 34 | #define _SQLITE3_H_ |
@@ -43,9 +41,37 @@ | ||
43 | 41 | extern "C" { |
44 | 42 | #endif |
45 | 43 | |
44 | + | |
46 | 45 | /* |
47 | -** Make sure these symbols where not defined by some previous header | |
48 | -** file. | |
46 | +** Add the ability to override 'extern' | |
47 | +*/ | |
48 | +#ifndef SQLITE_EXTERN | |
49 | +# define SQLITE_EXTERN extern | |
50 | +#endif | |
51 | + | |
52 | +#ifndef SQLITE_API | |
53 | +# define SQLITE_API | |
54 | +#endif | |
55 | + | |
56 | + | |
57 | +/* | |
58 | +** These no-op macros are used in front of interfaces to mark those | |
59 | +** interfaces as either deprecated or experimental. New applications | |
60 | +** should not use deprecated interfaces - they are support for backwards | |
61 | +** compatibility only. Application writers should be aware that | |
62 | +** experimental interfaces are subject to change in point releases. | |
63 | +** | |
64 | +** These macros used to resolve to various kinds of compiler magic that | |
65 | +** would generate warning messages when they were used. But that | |
66 | +** compiler magic ended up generating such a flurry of bug reports | |
67 | +** that we have taken it all out and gone back to using simple | |
68 | +** noop macros. | |
69 | +*/ | |
70 | +#define SQLITE_DEPRECATED | |
71 | +#define SQLITE_EXPERIMENTAL | |
72 | + | |
73 | +/* | |
74 | +** Ensure these symbols were not defined by some previous header file. | |
49 | 75 | */ |
50 | 76 | #ifdef SQLITE_VERSION |
51 | 77 | # undef SQLITE_VERSION |
@@ -55,77 +81,143 @@ extern "C" { | ||
55 | 81 | #endif |
56 | 82 | |
57 | 83 | /* |
58 | -** CAPI3REF: Compile-Time Library Version Numbers | |
84 | +** CAPI3REF: Compile-Time Library Version Numbers {H10010} <S60100> | |
59 | 85 | ** |
60 | -** The version of the SQLite library is contained in the sqlite3.h | |
61 | -** header file in a #define named SQLITE_VERSION. The SQLITE_VERSION | |
62 | -** macro resolves to a string constant. | |
86 | +** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in | |
87 | +** the sqlite3.h file specify the version of SQLite with which | |
88 | +** that header file is associated. | |
63 | 89 | ** |
64 | -** The format of the version string is "X.Y.Z", where | |
65 | -** X is the major version number, Y is the minor version number and Z | |
66 | -** is the release number. The X.Y.Z might be followed by "alpha" or "beta". | |
67 | -** For example "3.1.1beta". | |
68 | -** | |
69 | -** The X value is always 3 in SQLite. The X value only changes when | |
70 | -** backwards compatibility is broken and we intend to never break | |
71 | -** backwards compatibility. The Y value only changes when | |
90 | +** The "version" of SQLite is a string of the form "W.X.Y" or "W.X.Y.Z". | |
91 | +** The W value is major version number and is always 3 in SQLite3. | |
92 | +** The W value only changes when backwards compatibility is | |
93 | +** broken and we intend to never break backwards compatibility. | |
94 | +** The X value is the minor version number and only changes when | |
72 | 95 | ** there are major feature enhancements that are forwards compatible |
73 | -** but not backwards compatible. The Z value is incremented with | |
74 | -** each release but resets back to 0 when Y is incremented. | |
96 | +** but not backwards compatible. | |
97 | +** The Y value is the release number and is incremented with | |
98 | +** each release but resets back to 0 whenever X is incremented. | |
99 | +** The Z value only appears on branch releases. | |
75 | 100 | ** |
76 | -** The SQLITE_VERSION_NUMBER is an integer with the value | |
77 | -** (X*1000000 + Y*1000 + Z). For example, for version "3.1.1beta", | |
78 | -** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using | |
79 | -** version 3.1.1 or greater at compile time, programs may use the test | |
80 | -** (SQLITE_VERSION_NUMBER>=3001001). | |
101 | +** The SQLITE_VERSION_NUMBER is an integer that is computed as | |
102 | +** follows: | |
81 | 103 | ** |
82 | -** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()]. | |
104 | +** <blockquote><pre> | |
105 | +** SQLITE_VERSION_NUMBER = W*1000000 + X*1000 + Y | |
106 | +** </pre></blockquote> | |
107 | +** | |
108 | +** Since version 3.6.18, SQLite source code has been stored in the | |
109 | +** <a href="http://www.fossil-scm.org/">fossil configuration management | |
110 | +** system</a>. The SQLITE_SOURCE_ID | |
111 | +** macro is a string which identifies a particular check-in of SQLite | |
112 | +** within its configuration management system. The string contains the | |
113 | +** date and time of the check-in (UTC) and an SHA1 hash of the entire | |
114 | +** source tree. | |
115 | +** | |
116 | +** See also: [sqlite3_libversion()], | |
117 | +** [sqlite3_libversion_number()], [sqlite3_sourceid()], | |
118 | +** [sqlite_version()] and [sqlite_source_id()]. | |
119 | +** | |
120 | +** Requirements: [H10011] [H10014] | |
83 | 121 | */ |
84 | -#define SQLITE_VERSION "3.4.1" | |
85 | -#define SQLITE_VERSION_NUMBER 3004001 | |
122 | +#define SQLITE_VERSION "3.6.18" | |
123 | +#define SQLITE_VERSION_NUMBER 3006018 | |
124 | +#define SQLITE_SOURCE_ID "2009-09-11 14:05:07 b084828a771ec40be85f07c590ca99de4f6c24ee" | |
86 | 125 | |
87 | 126 | /* |
88 | -** CAPI3REF: Run-Time Library Version Numbers | |
127 | +** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100> | |
128 | +** KEYWORDS: sqlite3_version | |
129 | +** | |
130 | +** These interfaces provide the same information as the [SQLITE_VERSION], | |
131 | +** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] #defines in the header, | |
132 | +** but are associated with the library instead of the header file. Cautious | |
133 | +** programmers might include assert() statements in their application to | |
134 | +** verify that values returned by these interfaces match the macros in | |
135 | +** the header, and thus insure that the application is | |
136 | +** compiled with matching library and header files. | |
137 | +** | |
138 | +** <blockquote><pre> | |
139 | +** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER ); | |
140 | +** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 ); | |
141 | +** assert( strcmp(sqlite3_libversion,SQLITE_VERSION)==0 ); | |
142 | +** </pre></blockquote> | |
143 | +** | |
144 | +** The sqlite3_libversion() function returns the same information as is | |
145 | +** in the sqlite3_version[] string constant. The function is provided | |
146 | +** for use in DLLs since DLL users usually do not have direct access to string | |
147 | +** constants within the DLL. Similarly, the sqlite3_sourceid() function | |
148 | +** returns the same information as is in the [SQLITE_SOURCE_ID] #define of | |
149 | +** the header file. | |
89 | 150 | ** |
90 | -** These routines return values equivalent to the header constants | |
91 | -** [SQLITE_VERSION] and [SQLITE_VERSION_NUMBER]. The values returned | |
92 | -** by this routines should only be different from the header values | |
93 | -** if you compile your program using an sqlite3.h header from a | |
94 | -** different version of SQLite that the version of the library you | |
95 | -** link against. | |
151 | +** See also: [sqlite_version()] and [sqlite_source_id()]. | |
96 | 152 | ** |
97 | -** The sqlite3_version[] string constant contains the text of the | |
98 | -** [SQLITE_VERSION] string. The sqlite3_libversion() function returns | |
99 | -** a poiner to the sqlite3_version[] string constant. The function | |
100 | -** is provided for DLL users who can only access functions and not | |
101 | -** constants within the DLL. | |
153 | +** Requirements: [H10021] [H10022] [H10023] | |
102 | 154 | */ |
103 | -extern const char sqlite3_version[]; | |
104 | -const char *sqlite3_libversion(void); | |
105 | -int sqlite3_libversion_number(void); | |
155 | +SQLITE_API SQLITE_EXTERN const char sqlite3_version[]; | |
156 | +SQLITE_API const char *sqlite3_libversion(void); | |
157 | +SQLITE_API const char *sqlite3_sourceid(void); | |
158 | +SQLITE_API int sqlite3_libversion_number(void); | |
106 | 159 | |
107 | 160 | /* |
108 | -** CAPI3REF: Database Connection Handle | |
109 | -** | |
110 | -** Each open SQLite database is represented by pointer to an instance of the | |
111 | -** opaque structure named "sqlite3". It is useful to think of an sqlite3 | |
112 | -** pointer as an object. The [sqlite3_open] interface is its constructor | |
113 | -** and [sqlite3_close] is its destructor. There are many other interfaces | |
114 | -** (such as [sqlite3_prepare_v2], [sqlite3_create_function], and | |
115 | -** [sqlite3_busy_timeout] to name but three) that are methods on this | |
116 | -** object. | |
161 | +** CAPI3REF: Test To See If The Library Is Threadsafe {H10100} <S60100> | |
162 | +** | |
163 | +** SQLite can be compiled with or without mutexes. When | |
164 | +** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes | |
165 | +** are enabled and SQLite is threadsafe. When the | |
166 | +** [SQLITE_THREADSAFE] macro is 0, | |
167 | +** the mutexes are omitted. Without the mutexes, it is not safe | |
168 | +** to use SQLite concurrently from more than one thread. | |
169 | +** | |
170 | +** Enabling mutexes incurs a measurable performance penalty. | |
171 | +** So if speed is of utmost importance, it makes sense to disable | |
172 | +** the mutexes. But for maximum safety, mutexes should be enabled. | |
173 | +** The default behavior is for mutexes to be enabled. | |
174 | +** | |
175 | +** This interface can be used by an application to make sure that the | |
176 | +** version of SQLite that it is linking against was compiled with | |
177 | +** the desired setting of the [SQLITE_THREADSAFE] macro. | |
178 | +** | |
179 | +** This interface only reports on the compile-time mutex setting | |
180 | +** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with | |
181 | +** SQLITE_THREADSAFE=1 then mutexes are enabled by default but | |
182 | +** can be fully or partially disabled using a call to [sqlite3_config()] | |
183 | +** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD], | |
184 | +** or [SQLITE_CONFIG_MUTEX]. The return value of this function shows | |
185 | +** only the default compile-time setting, not any run-time changes | |
186 | +** to that setting. | |
187 | +** | |
188 | +** See the [threading mode] documentation for additional information. | |
189 | +** | |
190 | +** Requirements: [H10101] [H10102] | |
117 | 191 | */ |
118 | -typedef struct sqlite3 sqlite3; | |
192 | +SQLITE_API int sqlite3_threadsafe(void); | |
119 | 193 | |
194 | +/* | |
195 | +** CAPI3REF: Database Connection Handle {H12000} <S40200> | |
196 | +** KEYWORDS: {database connection} {database connections} | |
197 | +** | |
198 | +** Each open SQLite database is represented by a pointer to an instance of | |
199 | +** the opaque structure named "sqlite3". It is useful to think of an sqlite3 | |
200 | +** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and | |
201 | +** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()] | |
202 | +** is its destructor. There are many other interfaces (such as | |
203 | +** [sqlite3_prepare_v2()], [sqlite3_create_function()], and | |
204 | +** [sqlite3_busy_timeout()] to name but three) that are methods on an | |
205 | +** sqlite3 object. | |
206 | +*/ | |
207 | +typedef struct sqlite3 sqlite3; | |
120 | 208 | |
121 | 209 | /* |
122 | -** CAPI3REF: 64-Bit Integer Types | |
210 | +** CAPI3REF: 64-Bit Integer Types {H10200} <S10110> | |
211 | +** KEYWORDS: sqlite_int64 sqlite_uint64 | |
123 | 212 | ** |
124 | -** Some compilers do not support the "long long" datatype. So we have | |
125 | -** to do compiler-specific typedefs for 64-bit signed and unsigned integers. | |
213 | +** Because there is no cross-platform way to specify 64-bit integer types | |
214 | +** SQLite includes typedefs for 64-bit signed and unsigned integers. | |
126 | 215 | ** |
127 | -** Many SQLite interface functions require a 64-bit integer arguments. | |
128 | -** Those interfaces are declared using this typedef. | |
216 | +** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions. | |
217 | +** The sqlite_int64 and sqlite_uint64 types are supported for backwards | |
218 | +** compatibility only. | |
219 | +** | |
220 | +** Requirements: [H10201] [H10202] | |
129 | 221 | */ |
130 | 222 | #ifdef SQLITE_INT64_TYPE |
131 | 223 | typedef SQLITE_INT64_TYPE sqlite_int64; |
@@ -137,28 +229,48 @@ typedef struct sqlite3 sqlite3; | ||
137 | 229 | typedef long long int sqlite_int64; |
138 | 230 | typedef unsigned long long int sqlite_uint64; |
139 | 231 | #endif |
232 | +typedef sqlite_int64 sqlite3_int64; | |
233 | +typedef sqlite_uint64 sqlite3_uint64; | |
140 | 234 | |
141 | 235 | /* |
142 | 236 | ** If compiling for a processor that lacks floating point support, |
143 | -** substitute integer for floating-point | |
237 | +** substitute integer for floating-point. | |
144 | 238 | */ |
145 | 239 | #ifdef SQLITE_OMIT_FLOATING_POINT |
146 | -# define double sqlite_int64 | |
240 | +# define double sqlite3_int64 | |
147 | 241 | #endif |
148 | 242 | |
149 | 243 | /* |
150 | -** CAPI3REF: Closing A Database Connection | |
244 | +** CAPI3REF: Closing A Database Connection {H12010} <S30100><S40200> | |
245 | +** | |
246 | +** This routine is the destructor for the [sqlite3] object. | |
247 | +** | |
248 | +** Applications should [sqlite3_finalize | finalize] all [prepared statements] | |
249 | +** and [sqlite3_blob_close | close] all [BLOB handles] associated with | |
250 | +** the [sqlite3] object prior to attempting to close the object. | |
251 | +** The [sqlite3_next_stmt()] interface can be used to locate all | |
252 | +** [prepared statements] associated with a [database connection] if desired. | |
253 | +** Typical code might look like this: | |
254 | +** | |
255 | +** <blockquote><pre> | |
256 | +** sqlite3_stmt *pStmt; | |
257 | +** while( (pStmt = sqlite3_next_stmt(db, 0))!=0 ){ | |
258 | +** sqlite3_finalize(pStmt); | |
259 | +** } | |
260 | +** </pre></blockquote> | |
151 | 261 | ** |
152 | -** Call this function with a pointer to a structure that was previously | |
153 | -** returned from [sqlite3_open()] and the corresponding database will by | |
154 | -** closed. | |
262 | +** If [sqlite3_close()] is invoked while a transaction is open, | |
263 | +** the transaction is automatically rolled back. | |
155 | 264 | ** |
156 | -** All SQL statements prepared using [sqlite3_prepare_v2()] or | |
157 | -** [sqlite3_prepare16_v2()] must be destroyed using [sqlite3_finalize()] | |
158 | -** before this routine is called. Otherwise, SQLITE_BUSY is returned and the | |
159 | -** database connection remains open. | |
265 | +** The C parameter to [sqlite3_close(C)] must be either a NULL | |
266 | +** pointer or an [sqlite3] object pointer obtained | |
267 | +** from [sqlite3_open()], [sqlite3_open16()], or | |
268 | +** [sqlite3_open_v2()], and not previously closed. | |
269 | +** | |
270 | +** Requirements: | |
271 | +** [H12011] [H12012] [H12013] [H12014] [H12015] [H12019] | |
160 | 272 | */ |
161 | -int sqlite3_close(sqlite3 *); | |
273 | +SQLITE_API int sqlite3_close(sqlite3 *); | |
162 | 274 | |
163 | 275 | /* |
164 | 276 | ** The type for a callback function. |
@@ -168,76 +280,73 @@ int sqlite3_close(sqlite3 *); | ||
168 | 280 | typedef int (*sqlite3_callback)(void*,int,char**, char**); |
169 | 281 | |
170 | 282 | /* |
171 | -** CAPI3REF: One-Step Query Execution Interface | |
172 | -** | |
173 | -** This interface is used to do a one-time evaluatation of zero | |
174 | -** or more SQL statements. UTF-8 text of the SQL statements to | |
175 | -** be evaluted is passed in as the second parameter. The statements | |
176 | -** are prepared one by one using [sqlite3_prepare()], evaluated | |
177 | -** using [sqlite3_step()], then destroyed using [sqlite3_finalize()]. | |
178 | -** | |
179 | -** If one or more of the SQL statements are queries, then | |
180 | -** the callback function specified by the 3rd parameter is | |
181 | -** invoked once for each row of the query result. This callback | |
182 | -** should normally return 0. If the callback returns a non-zero | |
183 | -** value then the query is aborted, all subsequent SQL statements | |
184 | -** are skipped and the sqlite3_exec() function returns the SQLITE_ABORT. | |
185 | -** | |
186 | -** The 4th parameter to this interface is an arbitrary pointer that is | |
187 | -** passed through to the callback function as its first parameter. | |
188 | -** | |
189 | -** The 2nd parameter to the callback function is the number of | |
190 | -** columns in the query result. The 3rd parameter to the callback | |
191 | -** is an array of strings holding the values for each column | |
192 | -** as extracted using [sqlite3_column_text()]. | |
193 | -** The 4th parameter to the callback is an array of strings | |
194 | -** obtained using [sqlite3_column_name()] and holding | |
195 | -** the names of each column. | |
196 | -** | |
197 | -** The callback function may be NULL, even for queries. A NULL | |
198 | -** callback is not an error. It just means that no callback | |
199 | -** will be invoked. | |
200 | -** | |
201 | -** If an error occurs while parsing or evaluating the SQL (but | |
202 | -** not while executing the callback) then an appropriate error | |
203 | -** message is written into memory obtained from [sqlite3_malloc()] and | |
204 | -** *errmsg is made to point to that message. The calling function | |
205 | -** is responsible for freeing the memory that holds the error | |
206 | -** message. Use [sqlite3_free()] for this. If errmsg==NULL, | |
207 | -** then no error message is ever written. | |
208 | -** | |
209 | -** The return value is is SQLITE_OK if there are no errors and | |
210 | -** some other [SQLITE_OK | return code] if there is an error. | |
211 | -** The particular return value depends on the type of error. | |
212 | -** | |
283 | +** CAPI3REF: One-Step Query Execution Interface {H12100} <S10000> | |
284 | +** | |
285 | +** The sqlite3_exec() interface is a convenient way of running one or more | |
286 | +** SQL statements without having to write a lot of C code. The UTF-8 encoded | |
287 | +** SQL statements are passed in as the second parameter to sqlite3_exec(). | |
288 | +** The statements are evaluated one by one until either an error or | |
289 | +** an interrupt is encountered, or until they are all done. The 3rd parameter | |
290 | +** is an optional callback that is invoked once for each row of any query | |
291 | +** results produced by the SQL statements. The 5th parameter tells where | |
292 | +** to write any error messages. | |
293 | +** | |
294 | +** The error message passed back through the 5th parameter is held | |
295 | +** in memory obtained from [sqlite3_malloc()]. To avoid a memory leak, | |
296 | +** the calling application should call [sqlite3_free()] on any error | |
297 | +** message returned through the 5th parameter when it has finished using | |
298 | +** the error message. | |
299 | +** | |
300 | +** If the SQL statement in the 2nd parameter is NULL or an empty string | |
301 | +** or a string containing only whitespace and comments, then no SQL | |
302 | +** statements are evaluated and the database is not changed. | |
303 | +** | |
304 | +** The sqlite3_exec() interface is implemented in terms of | |
305 | +** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]. | |
306 | +** The sqlite3_exec() routine does nothing to the database that cannot be done | |
307 | +** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]. | |
308 | +** | |
309 | +** The first parameter to [sqlite3_exec()] must be an valid and open | |
310 | +** [database connection]. | |
311 | +** | |
312 | +** The database connection must not be closed while | |
313 | +** [sqlite3_exec()] is running. | |
314 | +** | |
315 | +** The calling function should use [sqlite3_free()] to free | |
316 | +** the memory that *errmsg is left pointing at once the error | |
317 | +** message is no longer needed. | |
318 | +** | |
319 | +** The SQL statement text in the 2nd parameter to [sqlite3_exec()] | |
320 | +** must remain unchanged while [sqlite3_exec()] is running. | |
321 | +** | |
322 | +** Requirements: | |
323 | +** [H12101] [H12102] [H12104] [H12105] [H12107] [H12110] [H12113] [H12116] | |
324 | +** [H12119] [H12122] [H12125] [H12131] [H12134] [H12137] [H12138] | |
213 | 325 | */ |
214 | -int sqlite3_exec( | |
326 | +SQLITE_API int sqlite3_exec( | |
215 | 327 | sqlite3*, /* An open database */ |
216 | - const char *sql, /* SQL to be evaluted */ | |
328 | + const char *sql, /* SQL to be evaluated */ | |
217 | 329 | int (*callback)(void*,int,char**,char**), /* Callback function */ |
218 | 330 | void *, /* 1st argument to callback */ |
219 | 331 | char **errmsg /* Error msg written here */ |
220 | 332 | ); |
221 | 333 | |
222 | 334 | /* |
223 | -** CAPI3REF: Result Codes | |
224 | -** KEYWORDS: SQLITE_OK | |
335 | +** CAPI3REF: Result Codes {H10210} <S10700> | |
336 | +** KEYWORDS: SQLITE_OK {error code} {error codes} | |
337 | +** KEYWORDS: {result code} {result codes} | |
225 | 338 | ** |
226 | 339 | ** Many SQLite functions return an integer result code from the set shown |
227 | -** above in order to indicates success or failure. | |
340 | +** here in order to indicates success or failure. | |
228 | 341 | ** |
229 | -** The result codes above are the only ones returned by SQLite in its | |
230 | -** default configuration. However, the [sqlite3_extended_result_codes()] | |
231 | -** API can be used to set a database connectoin to return more detailed | |
232 | -** result codes. | |
342 | +** New error codes may be added in future versions of SQLite. | |
233 | 343 | ** |
234 | 344 | ** See also: [SQLITE_IOERR_READ | extended result codes] |
235 | -** | |
236 | 345 | */ |
237 | 346 | #define SQLITE_OK 0 /* Successful result */ |
238 | 347 | /* beginning-of-error-codes */ |
239 | 348 | #define SQLITE_ERROR 1 /* SQL error or missing database */ |
240 | -#define SQLITE_INTERNAL 2 /* NOT USED. Internal logic error in SQLite */ | |
349 | +#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */ | |
241 | 350 | #define SQLITE_PERM 3 /* Access permission denied */ |
242 | 351 | #define SQLITE_ABORT 4 /* Callback routine requested an abort */ |
243 | 352 | #define SQLITE_BUSY 5 /* The database file is locked */ |
@@ -254,7 +363,7 @@ int sqlite3_exec( | ||
254 | 363 | #define SQLITE_EMPTY 16 /* Database is empty */ |
255 | 364 | #define SQLITE_SCHEMA 17 /* The database schema changed */ |
256 | 365 | #define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */ |
257 | -#define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */ | |
366 | +#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */ | |
258 | 367 | #define SQLITE_MISMATCH 20 /* Data type mismatch */ |
259 | 368 | #define SQLITE_MISUSE 21 /* Library used incorrectly */ |
260 | 369 | #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ |
@@ -267,202 +376,1126 @@ int sqlite3_exec( | ||
267 | 376 | /* end-of-error-codes */ |
268 | 377 | |
269 | 378 | /* |
270 | -** CAPI3REF: Extended Result Codes | |
379 | +** CAPI3REF: Extended Result Codes {H10220} <S10700> | |
380 | +** KEYWORDS: {extended error code} {extended error codes} | |
381 | +** KEYWORDS: {extended result code} {extended result codes} | |
271 | 382 | ** |
272 | 383 | ** In its default configuration, SQLite API routines return one of 26 integer |
273 | -** result codes described at result-codes. However, experience has shown that | |
274 | -** many of these result codes are too course-grained. They do not provide as | |
275 | -** much information about problems as users might like. In an effort to | |
384 | +** [SQLITE_OK | result codes]. However, experience has shown that many of | |
385 | +** these result codes are too coarse-grained. They do not provide as | |
386 | +** much information about problems as programmers might like. In an effort to | |
276 | 387 | ** address this, newer versions of SQLite (version 3.3.8 and later) include |
277 | 388 | ** support for additional result codes that provide more detailed information |
278 | -** about errors. The extended result codes are enabled (or disabled) for | |
279 | -** each database | |
280 | -** connection using the [sqlite3_extended_result_codes()] API. | |
281 | -** | |
282 | -** Some of the available extended result codes are listed above. | |
283 | -** We expect the number of extended result codes will be expand | |
389 | +** about errors. The extended result codes are enabled or disabled | |
390 | +** on a per database connection basis using the | |
391 | +** [sqlite3_extended_result_codes()] API. | |
392 | +** | |
393 | +** Some of the available extended result codes are listed here. | |
394 | +** One may expect the number of extended result codes will be expand | |
284 | 395 | ** over time. Software that uses extended result codes should expect |
285 | 396 | ** to see new result codes in future releases of SQLite. |
286 | -** | |
287 | -** The symbolic name for an extended result code always contains a related | |
288 | -** primary result code as a prefix. Primary result codes contain a single | |
289 | -** "_" character. Extended result codes contain two or more "_" characters. | |
290 | -** The numeric value of an extended result code can be converted to its | |
291 | -** corresponding primary result code by masking off the lower 8 bytes. | |
292 | 397 | ** |
293 | 398 | ** The SQLITE_OK result code will never be extended. It will always |
294 | 399 | ** be exactly zero. |
295 | 400 | */ |
296 | -#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) | |
297 | -#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) | |
298 | -#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) | |
299 | -#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) | |
300 | -#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) | |
301 | -#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) | |
302 | -#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) | |
303 | -#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) | |
304 | -#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) | |
305 | -#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) | |
306 | -#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) | |
401 | +#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) | |
402 | +#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) | |
403 | +#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) | |
404 | +#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) | |
405 | +#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) | |
406 | +#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) | |
407 | +#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) | |
408 | +#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) | |
409 | +#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) | |
410 | +#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) | |
411 | +#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) | |
412 | +#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8)) | |
413 | +#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8)) | |
414 | +#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8)) | |
415 | +#define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8)) | |
416 | +#define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8)) | |
417 | +#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8)) | |
418 | +#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8) ) | |
419 | + | |
420 | +/* | |
421 | +** CAPI3REF: Flags For File Open Operations {H10230} <H11120> <H12700> | |
422 | +** | |
423 | +** These bit values are intended for use in the | |
424 | +** 3rd parameter to the [sqlite3_open_v2()] interface and | |
425 | +** in the 4th parameter to the xOpen method of the | |
426 | +** [sqlite3_vfs] object. | |
427 | +*/ | |
428 | +#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */ | |
429 | +#define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */ | |
430 | +#define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */ | |
431 | +#define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */ | |
432 | +#define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */ | |
433 | +#define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */ | |
434 | +#define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */ | |
435 | +#define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */ | |
436 | +#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */ | |
437 | +#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */ | |
438 | +#define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */ | |
439 | +#define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */ | |
440 | +#define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */ | |
441 | +#define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */ | |
442 | +#define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */ | |
443 | +#define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */ | |
444 | + | |
445 | +/* | |
446 | +** CAPI3REF: Device Characteristics {H10240} <H11120> | |
447 | +** | |
448 | +** The xDeviceCapabilities method of the [sqlite3_io_methods] | |
449 | +** object returns an integer which is a vector of the these | |
450 | +** bit values expressing I/O characteristics of the mass storage | |
451 | +** device that holds the file that the [sqlite3_io_methods] | |
452 | +** refers to. | |
453 | +** | |
454 | +** The SQLITE_IOCAP_ATOMIC property means that all writes of | |
455 | +** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values | |
456 | +** mean that writes of blocks that are nnn bytes in size and | |
457 | +** are aligned to an address which is an integer multiple of | |
458 | +** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means | |
459 | +** that when data is appended to a file, the data is appended | |
460 | +** first then the size of the file is extended, never the other | |
461 | +** way around. The SQLITE_IOCAP_SEQUENTIAL property means that | |
462 | +** information is written to disk in the same order as calls | |
463 | +** to xWrite(). | |
464 | +*/ | |
465 | +#define SQLITE_IOCAP_ATOMIC 0x00000001 | |
466 | +#define SQLITE_IOCAP_ATOMIC512 0x00000002 | |
467 | +#define SQLITE_IOCAP_ATOMIC1K 0x00000004 | |
468 | +#define SQLITE_IOCAP_ATOMIC2K 0x00000008 | |
469 | +#define SQLITE_IOCAP_ATOMIC4K 0x00000010 | |
470 | +#define SQLITE_IOCAP_ATOMIC8K 0x00000020 | |
471 | +#define SQLITE_IOCAP_ATOMIC16K 0x00000040 | |
472 | +#define SQLITE_IOCAP_ATOMIC32K 0x00000080 | |
473 | +#define SQLITE_IOCAP_ATOMIC64K 0x00000100 | |
474 | +#define SQLITE_IOCAP_SAFE_APPEND 0x00000200 | |
475 | +#define SQLITE_IOCAP_SEQUENTIAL 0x00000400 | |
476 | + | |
477 | +/* | |
478 | +** CAPI3REF: File Locking Levels {H10250} <H11120> <H11310> | |
479 | +** | |
480 | +** SQLite uses one of these integer values as the second | |
481 | +** argument to calls it makes to the xLock() and xUnlock() methods | |
482 | +** of an [sqlite3_io_methods] object. | |
483 | +*/ | |
484 | +#define SQLITE_LOCK_NONE 0 | |
485 | +#define SQLITE_LOCK_SHARED 1 | |
486 | +#define SQLITE_LOCK_RESERVED 2 | |
487 | +#define SQLITE_LOCK_PENDING 3 | |
488 | +#define SQLITE_LOCK_EXCLUSIVE 4 | |
489 | + | |
490 | +/* | |
491 | +** CAPI3REF: Synchronization Type Flags {H10260} <H11120> | |
492 | +** | |
493 | +** When SQLite invokes the xSync() method of an | |
494 | +** [sqlite3_io_methods] object it uses a combination of | |
495 | +** these integer values as the second argument. | |
496 | +** | |
497 | +** When the SQLITE_SYNC_DATAONLY flag is used, it means that the | |
498 | +** sync operation only needs to flush data to mass storage. Inode | |
499 | +** information need not be flushed. If the lower four bits of the flag | |
500 | +** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics. | |
501 | +** If the lower four bits equal SQLITE_SYNC_FULL, that means | |
502 | +** to use Mac OS X style fullsync instead of fsync(). | |
503 | +*/ | |
504 | +#define SQLITE_SYNC_NORMAL 0x00002 | |
505 | +#define SQLITE_SYNC_FULL 0x00003 | |
506 | +#define SQLITE_SYNC_DATAONLY 0x00010 | |
507 | + | |
508 | +/* | |
509 | +** CAPI3REF: OS Interface Open File Handle {H11110} <S20110> | |
510 | +** | |
511 | +** An [sqlite3_file] object represents an open file in the | |
512 | +** [sqlite3_vfs | OS interface layer]. Individual OS interface | |
513 | +** implementations will | |
514 | +** want to subclass this object by appending additional fields | |
515 | +** for their own use. The pMethods entry is a pointer to an | |
516 | +** [sqlite3_io_methods] object that defines methods for performing | |
517 | +** I/O operations on the open file. | |
518 | +*/ | |
519 | +typedef struct sqlite3_file sqlite3_file; | |
520 | +struct sqlite3_file { | |
521 | + const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ | |
522 | +}; | |
307 | 523 | |
308 | 524 | /* |
309 | -** CAPI3REF: Enable Or Disable Extended Result Codes | |
525 | +** CAPI3REF: OS Interface File Virtual Methods Object {H11120} <S20110> | |
526 | +** | |
527 | +** Every file opened by the [sqlite3_vfs] xOpen method populates an | |
528 | +** [sqlite3_file] object (or, more commonly, a subclass of the | |
529 | +** [sqlite3_file] object) with a pointer to an instance of this object. | |
530 | +** This object defines the methods used to perform various operations | |
531 | +** against the open file represented by the [sqlite3_file] object. | |
532 | +** | |
533 | +** If the xOpen method sets the sqlite3_file.pMethods element | |
534 | +** to a non-NULL pointer, then the sqlite3_io_methods.xClose method | |
535 | +** may be invoked even if the xOpen reported that it failed. The | |
536 | +** only way to prevent a call to xClose following a failed xOpen | |
537 | +** is for the xOpen to set the sqlite3_file.pMethods element to NULL. | |
538 | +** | |
539 | +** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or | |
540 | +** [SQLITE_SYNC_FULL]. The first choice is the normal fsync(). | |
541 | +** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY] | |
542 | +** flag may be ORed in to indicate that only the data of the file | |
543 | +** and not its inode needs to be synced. | |
544 | +** | |
545 | +** The integer values to xLock() and xUnlock() are one of | |
546 | +** <ul> | |
547 | +** <li> [SQLITE_LOCK_NONE], | |
548 | +** <li> [SQLITE_LOCK_SHARED], | |
549 | +** <li> [SQLITE_LOCK_RESERVED], | |
550 | +** <li> [SQLITE_LOCK_PENDING], or | |
551 | +** <li> [SQLITE_LOCK_EXCLUSIVE]. | |
552 | +** </ul> | |
553 | +** xLock() increases the lock. xUnlock() decreases the lock. | |
554 | +** The xCheckReservedLock() method checks whether any database connection, | |
555 | +** either in this process or in some other process, is holding a RESERVED, | |
556 | +** PENDING, or EXCLUSIVE lock on the file. It returns true | |
557 | +** if such a lock exists and false otherwise. | |
558 | +** | |
559 | +** The xFileControl() method is a generic interface that allows custom | |
560 | +** VFS implementations to directly control an open file using the | |
561 | +** [sqlite3_file_control()] interface. The second "op" argument is an | |
562 | +** integer opcode. The third argument is a generic pointer intended to | |
563 | +** point to a structure that may contain arguments or space in which to | |
564 | +** write return values. Potential uses for xFileControl() might be | |
565 | +** functions to enable blocking locks with timeouts, to change the | |
566 | +** locking strategy (for example to use dot-file locks), to inquire | |
567 | +** about the status of a lock, or to break stale locks. The SQLite | |
568 | +** core reserves all opcodes less than 100 for its own use. | |
569 | +** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available. | |
570 | +** Applications that define a custom xFileControl method should use opcodes | |
571 | +** greater than 100 to avoid conflicts. | |
572 | +** | |
573 | +** The xSectorSize() method returns the sector size of the | |
574 | +** device that underlies the file. The sector size is the | |
575 | +** minimum write that can be performed without disturbing | |
576 | +** other bytes in the file. The xDeviceCharacteristics() | |
577 | +** method returns a bit vector describing behaviors of the | |
578 | +** underlying device: | |
310 | 579 | ** |
311 | -** This routine enables or disables the | |
312 | -** [SQLITE_IOERR_READ | extended result codes] feature. | |
313 | -** By default, SQLite API routines return one of only 26 integer | |
314 | -** [SQLITE_OK | result codes]. When extended result codes | |
315 | -** are enabled by this routine, the repetoire of result codes can be | |
316 | -** much larger and can (hopefully) provide more detailed information | |
317 | -** about the cause of an error. | |
580 | +** <ul> | |
581 | +** <li> [SQLITE_IOCAP_ATOMIC] | |
582 | +** <li> [SQLITE_IOCAP_ATOMIC512] | |
583 | +** <li> [SQLITE_IOCAP_ATOMIC1K] | |
584 | +** <li> [SQLITE_IOCAP_ATOMIC2K] | |
585 | +** <li> [SQLITE_IOCAP_ATOMIC4K] | |
586 | +** <li> [SQLITE_IOCAP_ATOMIC8K] | |
587 | +** <li> [SQLITE_IOCAP_ATOMIC16K] | |
588 | +** <li> [SQLITE_IOCAP_ATOMIC32K] | |
589 | +** <li> [SQLITE_IOCAP_ATOMIC64K] | |
590 | +** <li> [SQLITE_IOCAP_SAFE_APPEND] | |
591 | +** <li> [SQLITE_IOCAP_SEQUENTIAL] | |
592 | +** </ul> | |
318 | 593 | ** |
319 | -** The second argument is a boolean value that turns extended result | |
320 | -** codes on and off. Extended result codes are off by default for | |
321 | -** backwards compatibility with older versions of SQLite. | |
594 | +** The SQLITE_IOCAP_ATOMIC property means that all writes of | |
595 | +** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values | |
596 | +** mean that writes of blocks that are nnn bytes in size and | |
597 | +** are aligned to an address which is an integer multiple of | |
598 | +** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means | |
599 | +** that when data is appended to a file, the data is appended | |
600 | +** first then the size of the file is extended, never the other | |
601 | +** way around. The SQLITE_IOCAP_SEQUENTIAL property means that | |
602 | +** information is written to disk in the same order as calls | |
603 | +** to xWrite(). | |
604 | +** | |
605 | +** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill | |
606 | +** in the unread portions of the buffer with zeros. A VFS that | |
607 | +** fails to zero-fill short reads might seem to work. However, | |
608 | +** failure to zero-fill short reads will eventually lead to | |
609 | +** database corruption. | |
322 | 610 | */ |
323 | -int sqlite3_extended_result_codes(sqlite3*, int onoff); | |
611 | +typedef struct sqlite3_io_methods sqlite3_io_methods; | |
612 | +struct sqlite3_io_methods { | |
613 | + int iVersion; | |
614 | + int (*xClose)(sqlite3_file*); | |
615 | + int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst); | |
616 | + int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst); | |
617 | + int (*xTruncate)(sqlite3_file*, sqlite3_int64 size); | |
618 | + int (*xSync)(sqlite3_file*, int flags); | |
619 | + int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize); | |
620 | + int (*xLock)(sqlite3_file*, int); | |
621 | + int (*xUnlock)(sqlite3_file*, int); | |
622 | + int (*xCheckReservedLock)(sqlite3_file*, int *pResOut); | |
623 | + int (*xFileControl)(sqlite3_file*, int op, void *pArg); | |
624 | + int (*xSectorSize)(sqlite3_file*); | |
625 | + int (*xDeviceCharacteristics)(sqlite3_file*); | |
626 | + /* Additional methods may be added in future releases */ | |
627 | +}; | |
324 | 628 | |
325 | 629 | /* |
326 | -** CAPI3REF: Last Insert Rowid | |
630 | +** CAPI3REF: Standard File Control Opcodes {H11310} <S30800> | |
631 | +** | |
632 | +** These integer constants are opcodes for the xFileControl method | |
633 | +** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()] | |
634 | +** interface. | |
635 | +** | |
636 | +** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This | |
637 | +** opcode causes the xFileControl method to write the current state of | |
638 | +** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED], | |
639 | +** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE]) | |
640 | +** into an integer that the pArg argument points to. This capability | |
641 | +** is used during testing and only needs to be supported when SQLITE_TEST | |
642 | +** is defined. | |
643 | +*/ | |
644 | +#define SQLITE_FCNTL_LOCKSTATE 1 | |
645 | +#define SQLITE_GET_LOCKPROXYFILE 2 | |
646 | +#define SQLITE_SET_LOCKPROXYFILE 3 | |
647 | +#define SQLITE_LAST_ERRNO 4 | |
648 | + | |
649 | +/* | |
650 | +** CAPI3REF: Mutex Handle {H17110} <S20130> | |
651 | +** | |
652 | +** The mutex module within SQLite defines [sqlite3_mutex] to be an | |
653 | +** abstract type for a mutex object. The SQLite core never looks | |
654 | +** at the internal representation of an [sqlite3_mutex]. It only | |
655 | +** deals with pointers to the [sqlite3_mutex] object. | |
656 | +** | |
657 | +** Mutexes are created using [sqlite3_mutex_alloc()]. | |
658 | +*/ | |
659 | +typedef struct sqlite3_mutex sqlite3_mutex; | |
660 | + | |
661 | +/* | |
662 | +** CAPI3REF: OS Interface Object {H11140} <S20100> | |
663 | +** | |
664 | +** An instance of the sqlite3_vfs object defines the interface between | |
665 | +** the SQLite core and the underlying operating system. The "vfs" | |
666 | +** in the name of the object stands for "virtual file system". | |
667 | +** | |
668 | +** The value of the iVersion field is initially 1 but may be larger in | |
669 | +** future versions of SQLite. Additional fields may be appended to this | |
670 | +** object when the iVersion value is increased. Note that the structure | |
671 | +** of the sqlite3_vfs object changes in the transaction between | |
672 | +** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not | |
673 | +** modified. | |
674 | +** | |
675 | +** The szOsFile field is the size of the subclassed [sqlite3_file] | |
676 | +** structure used by this VFS. mxPathname is the maximum length of | |
677 | +** a pathname in this VFS. | |
678 | +** | |
679 | +** Registered sqlite3_vfs objects are kept on a linked list formed by | |
680 | +** the pNext pointer. The [sqlite3_vfs_register()] | |
681 | +** and [sqlite3_vfs_unregister()] interfaces manage this list | |
682 | +** in a thread-safe way. The [sqlite3_vfs_find()] interface | |
683 | +** searches the list. Neither the application code nor the VFS | |
684 | +** implementation should use the pNext pointer. | |
685 | +** | |
686 | +** The pNext field is the only field in the sqlite3_vfs | |
687 | +** structure that SQLite will ever modify. SQLite will only access | |
688 | +** or modify this field while holding a particular static mutex. | |
689 | +** The application should never modify anything within the sqlite3_vfs | |
690 | +** object once the object has been registered. | |
691 | +** | |
692 | +** The zName field holds the name of the VFS module. The name must | |
693 | +** be unique across all VFS modules. | |
694 | +** | |
695 | +** SQLite will guarantee that the zFilename parameter to xOpen | |
696 | +** is either a NULL pointer or string obtained | |
697 | +** from xFullPathname(). SQLite further guarantees that | |
698 | +** the string will be valid and unchanged until xClose() is | |
699 | +** called. Because of the previous sentence, | |
700 | +** the [sqlite3_file] can safely store a pointer to the | |
701 | +** filename if it needs to remember the filename for some reason. | |
702 | +** If the zFilename parameter is xOpen is a NULL pointer then xOpen | |
703 | +** must invent its own temporary name for the file. Whenever the | |
704 | +** xFilename parameter is NULL it will also be the case that the | |
705 | +** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE]. | |
706 | +** | |
707 | +** The flags argument to xOpen() includes all bits set in | |
708 | +** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()] | |
709 | +** or [sqlite3_open16()] is used, then flags includes at least | |
710 | +** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. | |
711 | +** If xOpen() opens a file read-only then it sets *pOutFlags to | |
712 | +** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set. | |
713 | +** | |
714 | +** SQLite will also add one of the following flags to the xOpen() | |
715 | +** call, depending on the object being opened: | |
327 | 716 | ** |
328 | -** Each entry in an SQLite table has a unique 64-bit signed integer key | |
329 | -** called the "rowid". The rowid is always available as an undeclared | |
330 | -** column named ROWID, OID, or _ROWID_. If the table has a column of | |
331 | -** type INTEGER PRIMARY KEY then that column is another an alias for the | |
332 | -** rowid. | |
717 | +** <ul> | |
718 | +** <li> [SQLITE_OPEN_MAIN_DB] | |
719 | +** <li> [SQLITE_OPEN_MAIN_JOURNAL] | |
720 | +** <li> [SQLITE_OPEN_TEMP_DB] | |
721 | +** <li> [SQLITE_OPEN_TEMP_JOURNAL] | |
722 | +** <li> [SQLITE_OPEN_TRANSIENT_DB] | |
723 | +** <li> [SQLITE_OPEN_SUBJOURNAL] | |
724 | +** <li> [SQLITE_OPEN_MASTER_JOURNAL] | |
725 | +** </ul> | |
726 | +** | |
727 | +** The file I/O implementation can use the object type flags to | |
728 | +** change the way it deals with files. For example, an application | |
729 | +** that does not care about crash recovery or rollback might make | |
730 | +** the open of a journal file a no-op. Writes to this journal would | |
731 | +** also be no-ops, and any attempt to read the journal would return | |
732 | +** SQLITE_IOERR. Or the implementation might recognize that a database | |
733 | +** file will be doing page-aligned sector reads and writes in a random | |
734 | +** order and set up its I/O subsystem accordingly. | |
735 | +** | |
736 | +** SQLite might also add one of the following flags to the xOpen method: | |
737 | +** | |
738 | +** <ul> | |
739 | +** <li> [SQLITE_OPEN_DELETEONCLOSE] | |
740 | +** <li> [SQLITE_OPEN_EXCLUSIVE] | |
741 | +** </ul> | |
333 | 742 | ** |
334 | -** This routine returns the rowid of the most recent INSERT into | |
335 | -** the database from the database connection given in the first | |
336 | -** argument. If no inserts have ever occurred on this database | |
337 | -** connection, zero is returned. | |
743 | +** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be | |
744 | +** deleted when it is closed. The [SQLITE_OPEN_DELETEONCLOSE] | |
745 | +** will be set for TEMP databases, journals and for subjournals. | |
746 | +** | |
747 | +** The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction | |
748 | +** with the [SQLITE_OPEN_CREATE] flag, which are both directly | |
749 | +** analogous to the O_EXCL and O_CREAT flags of the POSIX open() | |
750 | +** API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the | |
751 | +** SQLITE_OPEN_CREATE, is used to indicate that file should always | |
752 | +** be created, and that it is an error if it already exists. | |
753 | +** It is <i>not</i> used to indicate the file should be opened | |
754 | +** for exclusive access. | |
755 | +** | |
756 | +** At least szOsFile bytes of memory are allocated by SQLite | |
757 | +** to hold the [sqlite3_file] structure passed as the third | |
758 | +** argument to xOpen. The xOpen method does not have to | |
759 | +** allocate the structure; it should just fill it in. Note that | |
760 | +** the xOpen method must set the sqlite3_file.pMethods to either | |
761 | +** a valid [sqlite3_io_methods] object or to NULL. xOpen must do | |
762 | +** this even if the open fails. SQLite expects that the sqlite3_file.pMethods | |
763 | +** element will be valid after xOpen returns regardless of the success | |
764 | +** or failure of the xOpen call. | |
765 | +** | |
766 | +** The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] | |
767 | +** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to | |
768 | +** test whether a file is readable and writable, or [SQLITE_ACCESS_READ] | |
769 | +** to test whether a file is at least readable. The file can be a | |
770 | +** directory. | |
771 | +** | |
772 | +** SQLite will always allocate at least mxPathname+1 bytes for the | |
773 | +** output buffer xFullPathname. The exact size of the output buffer | |
774 | +** is also passed as a parameter to both methods. If the output buffer | |
775 | +** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is | |
776 | +** handled as a fatal error by SQLite, vfs implementations should endeavor | |
777 | +** to prevent this by setting mxPathname to a sufficiently large value. | |
778 | +** | |
779 | +** The xRandomness(), xSleep(), and xCurrentTime() interfaces | |
780 | +** are not strictly a part of the filesystem, but they are | |
781 | +** included in the VFS structure for completeness. | |
782 | +** The xRandomness() function attempts to return nBytes bytes | |
783 | +** of good-quality randomness into zOut. The return value is | |
784 | +** the actual number of bytes of randomness obtained. | |
785 | +** The xSleep() method causes the calling thread to sleep for at | |
786 | +** least the number of microseconds given. The xCurrentTime() | |
787 | +** method returns a Julian Day Number for the current date and time. | |
338 | 788 | ** |
339 | -** If an INSERT occurs within a trigger, then the rowid of the | |
340 | -** inserted row is returned by this routine as long as the trigger | |
341 | -** is running. But once the trigger terminates, the value returned | |
342 | -** by this routine reverts to the last value inserted before the | |
343 | -** trigger fired. | |
344 | 789 | */ |
345 | -sqlite_int64 sqlite3_last_insert_rowid(sqlite3*); | |
790 | +typedef struct sqlite3_vfs sqlite3_vfs; | |
791 | +struct sqlite3_vfs { | |
792 | + int iVersion; /* Structure version number */ | |
793 | + int szOsFile; /* Size of subclassed sqlite3_file */ | |
794 | + int mxPathname; /* Maximum file pathname length */ | |
795 | + sqlite3_vfs *pNext; /* Next registered VFS */ | |
796 | + const char *zName; /* Name of this virtual file system */ | |
797 | + void *pAppData; /* Pointer to application-specific data */ | |
798 | + int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*, | |
799 | + int flags, int *pOutFlags); | |
800 | + int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir); | |
801 | + int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut); | |
802 | + int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut); | |
803 | + void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename); | |
804 | + void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg); | |
805 | + void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void); | |
806 | + void (*xDlClose)(sqlite3_vfs*, void*); | |
807 | + int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut); | |
808 | + int (*xSleep)(sqlite3_vfs*, int microseconds); | |
809 | + int (*xCurrentTime)(sqlite3_vfs*, double*); | |
810 | + int (*xGetLastError)(sqlite3_vfs*, int, char *); | |
811 | + /* New fields may be appended in figure versions. The iVersion | |
812 | + ** value will increment whenever this happens. */ | |
813 | +}; | |
814 | + | |
815 | +/* | |
816 | +** CAPI3REF: Flags for the xAccess VFS method {H11190} <H11140> | |
817 | +** | |
818 | +** These integer constants can be used as the third parameter to | |
819 | +** the xAccess method of an [sqlite3_vfs] object. {END} They determine | |
820 | +** what kind of permissions the xAccess method is looking for. | |
821 | +** With SQLITE_ACCESS_EXISTS, the xAccess method | |
822 | +** simply checks whether the file exists. | |
823 | +** With SQLITE_ACCESS_READWRITE, the xAccess method | |
824 | +** checks whether the file is both readable and writable. | |
825 | +** With SQLITE_ACCESS_READ, the xAccess method | |
826 | +** checks whether the file is readable. | |
827 | +*/ | |
828 | +#define SQLITE_ACCESS_EXISTS 0 | |
829 | +#define SQLITE_ACCESS_READWRITE 1 | |
830 | +#define SQLITE_ACCESS_READ 2 | |
346 | 831 | |
347 | 832 | /* |
348 | -** CAPI3REF: Count The Number Of Rows Modified | |
833 | +** CAPI3REF: Initialize The SQLite Library {H10130} <S20000><S30100> | |
834 | +** | |
835 | +** The sqlite3_initialize() routine initializes the | |
836 | +** SQLite library. The sqlite3_shutdown() routine | |
837 | +** deallocates any resources that were allocated by sqlite3_initialize(). | |
838 | +** | |
839 | +** A call to sqlite3_initialize() is an "effective" call if it is | |
840 | +** the first time sqlite3_initialize() is invoked during the lifetime of | |
841 | +** the process, or if it is the first time sqlite3_initialize() is invoked | |
842 | +** following a call to sqlite3_shutdown(). Only an effective call | |
843 | +** of sqlite3_initialize() does any initialization. All other calls | |
844 | +** are harmless no-ops. | |
845 | +** | |
846 | +** A call to sqlite3_shutdown() is an "effective" call if it is the first | |
847 | +** call to sqlite3_shutdown() since the last sqlite3_initialize(). Only | |
848 | +** an effective call to sqlite3_shutdown() does any deinitialization. | |
849 | +** All other calls to sqlite3_shutdown() are harmless no-ops. | |
850 | +** | |
851 | +** Among other things, sqlite3_initialize() shall invoke | |
852 | +** sqlite3_os_init(). Similarly, sqlite3_shutdown() | |
853 | +** shall invoke sqlite3_os_end(). | |
854 | +** | |
855 | +** The sqlite3_initialize() routine returns [SQLITE_OK] on success. | |
856 | +** If for some reason, sqlite3_initialize() is unable to initialize | |
857 | +** the library (perhaps it is unable to allocate a needed resource such | |
858 | +** as a mutex) it returns an [error code] other than [SQLITE_OK]. | |
859 | +** | |
860 | +** The sqlite3_initialize() routine is called internally by many other | |
861 | +** SQLite interfaces so that an application usually does not need to | |
862 | +** invoke sqlite3_initialize() directly. For example, [sqlite3_open()] | |
863 | +** calls sqlite3_initialize() so the SQLite library will be automatically | |
864 | +** initialized when [sqlite3_open()] is called if it has not be initialized | |
865 | +** already. However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT] | |
866 | +** compile-time option, then the automatic calls to sqlite3_initialize() | |
867 | +** are omitted and the application must call sqlite3_initialize() directly | |
868 | +** prior to using any other SQLite interface. For maximum portability, | |
869 | +** it is recommended that applications always invoke sqlite3_initialize() | |
870 | +** directly prior to using any other SQLite interface. Future releases | |
871 | +** of SQLite may require this. In other words, the behavior exhibited | |
872 | +** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the | |
873 | +** default behavior in some future release of SQLite. | |
874 | +** | |
875 | +** The sqlite3_os_init() routine does operating-system specific | |
876 | +** initialization of the SQLite library. The sqlite3_os_end() | |
877 | +** routine undoes the effect of sqlite3_os_init(). Typical tasks | |
878 | +** performed by these routines include allocation or deallocation | |
879 | +** of static resources, initialization of global variables, | |
880 | +** setting up a default [sqlite3_vfs] module, or setting up | |
881 | +** a default configuration using [sqlite3_config()]. | |
882 | +** | |
883 | +** The application should never invoke either sqlite3_os_init() | |
884 | +** or sqlite3_os_end() directly. The application should only invoke | |
885 | +** sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init() | |
886 | +** interface is called automatically by sqlite3_initialize() and | |
887 | +** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate | |
888 | +** implementations for sqlite3_os_init() and sqlite3_os_end() | |
889 | +** are built into SQLite when it is compiled for Unix, Windows, or OS/2. | |
890 | +** When [custom builds | built for other platforms] | |
891 | +** (using the [SQLITE_OS_OTHER=1] compile-time | |
892 | +** option) the application must supply a suitable implementation for | |
893 | +** sqlite3_os_init() and sqlite3_os_end(). An application-supplied | |
894 | +** implementation of sqlite3_os_init() or sqlite3_os_end() | |
895 | +** must return [SQLITE_OK] on success and some other [error code] upon | |
896 | +** failure. | |
897 | +*/ | |
898 | +SQLITE_API int sqlite3_initialize(void); | |
899 | +SQLITE_API int sqlite3_shutdown(void); | |
900 | +SQLITE_API int sqlite3_os_init(void); | |
901 | +SQLITE_API int sqlite3_os_end(void); | |
902 | + | |
903 | +/* | |
904 | +** CAPI3REF: Configuring The SQLite Library {H14100} <S20000><S30200> | |
905 | +** EXPERIMENTAL | |
906 | +** | |
907 | +** The sqlite3_config() interface is used to make global configuration | |
908 | +** changes to SQLite in order to tune SQLite to the specific needs of | |
909 | +** the application. The default configuration is recommended for most | |
910 | +** applications and so this routine is usually not necessary. It is | |
911 | +** provided to support rare applications with unusual needs. | |
912 | +** | |
913 | +** The sqlite3_config() interface is not threadsafe. The application | |
914 | +** must insure that no other SQLite interfaces are invoked by other | |
915 | +** threads while sqlite3_config() is running. Furthermore, sqlite3_config() | |
916 | +** may only be invoked prior to library initialization using | |
917 | +** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()]. | |
918 | +** Note, however, that sqlite3_config() can be called as part of the | |
919 | +** implementation of an application-defined [sqlite3_os_init()]. | |
920 | +** | |
921 | +** The first argument to sqlite3_config() is an integer | |
922 | +** [SQLITE_CONFIG_SINGLETHREAD | configuration option] that determines | |
923 | +** what property of SQLite is to be configured. Subsequent arguments | |
924 | +** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option] | |
925 | +** in the first argument. | |
926 | +** | |
927 | +** When a configuration option is set, sqlite3_config() returns [SQLITE_OK]. | |
928 | +** If the option is unknown or SQLite is unable to set the option | |
929 | +** then this routine returns a non-zero [error code]. | |
930 | +** | |
931 | +** Requirements: | |
932 | +** [H14103] [H14106] [H14120] [H14123] [H14126] [H14129] [H14132] [H14135] | |
933 | +** [H14138] [H14141] [H14144] [H14147] [H14150] [H14153] [H14156] [H14159] | |
934 | +** [H14162] [H14165] [H14168] | |
935 | +*/ | |
936 | +SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_config(int, ...); | |
937 | + | |
938 | +/* | |
939 | +** CAPI3REF: Configure database connections {H14200} <S20000> | |
940 | +** EXPERIMENTAL | |
941 | +** | |
942 | +** The sqlite3_db_config() interface is used to make configuration | |
943 | +** changes to a [database connection]. The interface is similar to | |
944 | +** [sqlite3_config()] except that the changes apply to a single | |
945 | +** [database connection] (specified in the first argument). The | |
946 | +** sqlite3_db_config() interface can only be used immediately after | |
947 | +** the database connection is created using [sqlite3_open()], | |
948 | +** [sqlite3_open16()], or [sqlite3_open_v2()]. | |
949 | +** | |
950 | +** The second argument to sqlite3_db_config(D,V,...) is the | |
951 | +** configuration verb - an integer code that indicates what | |
952 | +** aspect of the [database connection] is being configured. | |
953 | +** The only choice for this value is [SQLITE_DBCONFIG_LOOKASIDE]. | |
954 | +** New verbs are likely to be added in future releases of SQLite. | |
955 | +** Additional arguments depend on the verb. | |
956 | +** | |
957 | +** Requirements: | |
958 | +** [H14203] [H14206] [H14209] [H14212] [H14215] | |
959 | +*/ | |
960 | +SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...); | |
961 | + | |
962 | +/* | |
963 | +** CAPI3REF: Memory Allocation Routines {H10155} <S20120> | |
964 | +** EXPERIMENTAL | |
965 | +** | |
966 | +** An instance of this object defines the interface between SQLite | |
967 | +** and low-level memory allocation routines. | |
968 | +** | |
969 | +** This object is used in only one place in the SQLite interface. | |
970 | +** A pointer to an instance of this object is the argument to | |
971 | +** [sqlite3_config()] when the configuration option is | |
972 | +** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC]. | |
973 | +** By creating an instance of this object | |
974 | +** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC]) | |
975 | +** during configuration, an application can specify an alternative | |
976 | +** memory allocation subsystem for SQLite to use for all of its | |
977 | +** dynamic memory needs. | |
978 | +** | |
979 | +** Note that SQLite comes with several [built-in memory allocators] | |
980 | +** that are perfectly adequate for the overwhelming majority of applications | |
981 | +** and that this object is only useful to a tiny minority of applications | |
982 | +** with specialized memory allocation requirements. This object is | |
983 | +** also used during testing of SQLite in order to specify an alternative | |
984 | +** memory allocator that simulates memory out-of-memory conditions in | |
985 | +** order to verify that SQLite recovers gracefully from such | |
986 | +** conditions. | |
987 | +** | |
988 | +** The xMalloc and xFree methods must work like the | |
989 | +** malloc() and free() functions from the standard C library. | |
990 | +** The xRealloc method must work like realloc() from the standard C library | |
991 | +** with the exception that if the second argument to xRealloc is zero, | |
992 | +** xRealloc must be a no-op - it must not perform any allocation or | |
993 | +** deallocation. SQLite guaranteeds that the second argument to | |
994 | +** xRealloc is always a value returned by a prior call to xRoundup. | |
995 | +** And so in cases where xRoundup always returns a positive number, | |
996 | +** xRealloc can perform exactly as the standard library realloc() and | |
997 | +** still be in compliance with this specification. | |
998 | +** | |
999 | +** xSize should return the allocated size of a memory allocation | |
1000 | +** previously obtained from xMalloc or xRealloc. The allocated size | |
1001 | +** is always at least as big as the requested size but may be larger. | |
1002 | +** | |
1003 | +** The xRoundup method returns what would be the allocated size of | |
1004 | +** a memory allocation given a particular requested size. Most memory | |
1005 | +** allocators round up memory allocations at least to the next multiple | |
1006 | +** of 8. Some allocators round up to a larger multiple or to a power of 2. | |
1007 | +** Every memory allocation request coming in through [sqlite3_malloc()] | |
1008 | +** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0, | |
1009 | +** that causes the corresponding memory allocation to fail. | |
1010 | +** | |
1011 | +** The xInit method initializes the memory allocator. (For example, | |
1012 | +** it might allocate any require mutexes or initialize internal data | |
1013 | +** structures. The xShutdown method is invoked (indirectly) by | |
1014 | +** [sqlite3_shutdown()] and should deallocate any resources acquired | |
1015 | +** by xInit. The pAppData pointer is used as the only parameter to | |
1016 | +** xInit and xShutdown. | |
1017 | +** | |
1018 | +** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes | |
1019 | +** the xInit method, so the xInit method need not be threadsafe. The | |
1020 | +** xShutdown method is only called from [sqlite3_shutdown()] so it does | |
1021 | +** not need to be threadsafe either. For all other methods, SQLite | |
1022 | +** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the | |
1023 | +** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which | |
1024 | +** it is by default) and so the methods are automatically serialized. | |
1025 | +** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other | |
1026 | +** methods must be threadsafe or else make their own arrangements for | |
1027 | +** serialization. | |
1028 | +** | |
1029 | +** SQLite will never invoke xInit() more than once without an intervening | |
1030 | +** call to xShutdown(). | |
1031 | +*/ | |
1032 | +typedef struct sqlite3_mem_methods sqlite3_mem_methods; | |
1033 | +struct sqlite3_mem_methods { | |
1034 | + void *(*xMalloc)(int); /* Memory allocation function */ | |
1035 | + void (*xFree)(void*); /* Free a prior allocation */ | |
1036 | + void *(*xRealloc)(void*,int); /* Resize an allocation */ | |
1037 | + int (*xSize)(void*); /* Return the size of an allocation */ | |
1038 | + int (*xRoundup)(int); /* Round up request size to allocation size */ | |
1039 | + int (*xInit)(void*); /* Initialize the memory allocator */ | |
1040 | + void (*xShutdown)(void*); /* Deinitialize the memory allocator */ | |
1041 | + void *pAppData; /* Argument to xInit() and xShutdown() */ | |
1042 | +}; | |
1043 | + | |
1044 | +/* | |
1045 | +** CAPI3REF: Configuration Options {H10160} <S20000> | |
1046 | +** EXPERIMENTAL | |
1047 | +** | |
1048 | +** These constants are the available integer configuration options that | |
1049 | +** can be passed as the first argument to the [sqlite3_config()] interface. | |
1050 | +** | |
1051 | +** New configuration options may be added in future releases of SQLite. | |
1052 | +** Existing configuration options might be discontinued. Applications | |
1053 | +** should check the return code from [sqlite3_config()] to make sure that | |
1054 | +** the call worked. The [sqlite3_config()] interface will return a | |
1055 | +** non-zero [error code] if a discontinued or unsupported configuration option | |
1056 | +** is invoked. | |
1057 | +** | |
1058 | +** <dl> | |
1059 | +** <dt>SQLITE_CONFIG_SINGLETHREAD</dt> | |
1060 | +** <dd>There are no arguments to this option. This option disables | |
1061 | +** all mutexing and puts SQLite into a mode where it can only be used | |
1062 | +** by a single thread.</dd> | |
1063 | +** | |
1064 | +** <dt>SQLITE_CONFIG_MULTITHREAD</dt> | |
1065 | +** <dd>There are no arguments to this option. This option disables | |
1066 | +** mutexing on [database connection] and [prepared statement] objects. | |
1067 | +** The application is responsible for serializing access to | |
1068 | +** [database connections] and [prepared statements]. But other mutexes | |
1069 | +** are enabled so that SQLite will be safe to use in a multi-threaded | |
1070 | +** environment as long as no two threads attempt to use the same | |
1071 | +** [database connection] at the same time. See the [threading mode] | |
1072 | +** documentation for additional information.</dd> | |
1073 | +** | |
1074 | +** <dt>SQLITE_CONFIG_SERIALIZED</dt> | |
1075 | +** <dd>There are no arguments to this option. This option enables | |
1076 | +** all mutexes including the recursive | |
1077 | +** mutexes on [database connection] and [prepared statement] objects. | |
1078 | +** In this mode (which is the default when SQLite is compiled with | |
1079 | +** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access | |
1080 | +** to [database connections] and [prepared statements] so that the | |
1081 | +** application is free to use the same [database connection] or the | |
1082 | +** same [prepared statement] in different threads at the same time. | |
1083 | +** See the [threading mode] documentation for additional information.</dd> | |
1084 | +** | |
1085 | +** <dt>SQLITE_CONFIG_MALLOC</dt> | |
1086 | +** <dd>This option takes a single argument which is a pointer to an | |
1087 | +** instance of the [sqlite3_mem_methods] structure. The argument specifies | |
1088 | +** alternative low-level memory allocation routines to be used in place of | |
1089 | +** the memory allocation routines built into SQLite.</dd> | |
1090 | +** | |
1091 | +** <dt>SQLITE_CONFIG_GETMALLOC</dt> | |
1092 | +** <dd>This option takes a single argument which is a pointer to an | |
1093 | +** instance of the [sqlite3_mem_methods] structure. The [sqlite3_mem_methods] | |
1094 | +** structure is filled with the currently defined memory allocation routines. | |
1095 | +** This option can be used to overload the default memory allocation | |
1096 | +** routines with a wrapper that simulations memory allocation failure or | |
1097 | +** tracks memory usage, for example.</dd> | |
1098 | +** | |
1099 | +** <dt>SQLITE_CONFIG_MEMSTATUS</dt> | |
1100 | +** <dd>This option takes single argument of type int, interpreted as a | |
1101 | +** boolean, which enables or disables the collection of memory allocation | |
1102 | +** statistics. When disabled, the following SQLite interfaces become | |
1103 | +** non-operational: | |
1104 | +** <ul> | |
1105 | +** <li> [sqlite3_memory_used()] | |
1106 | +** <li> [sqlite3_memory_highwater()] | |
1107 | +** <li> [sqlite3_soft_heap_limit()] | |
1108 | +** <li> [sqlite3_status()] | |
1109 | +** </ul> | |
1110 | +** </dd> | |
1111 | +** | |
1112 | +** <dt>SQLITE_CONFIG_SCRATCH</dt> | |
1113 | +** <dd>This option specifies a static memory buffer that SQLite can use for | |
1114 | +** scratch memory. There are three arguments: A pointer an 8-byte | |
1115 | +** aligned memory buffer from which the scrach allocations will be | |
1116 | +** drawn, the size of each scratch allocation (sz), | |
1117 | +** and the maximum number of scratch allocations (N). The sz | |
1118 | +** argument must be a multiple of 16. The sz parameter should be a few bytes | |
1119 | +** larger than the actual scratch space required due to internal overhead. | |
1120 | +** The first argument should pointer to an 8-byte aligned buffer | |
1121 | +** of at least sz*N bytes of memory. | |
1122 | +** SQLite will use no more than one scratch buffer at once per thread, so | |
1123 | +** N should be set to the expected maximum number of threads. The sz | |
1124 | +** parameter should be 6 times the size of the largest database page size. | |
1125 | +** Scratch buffers are used as part of the btree balance operation. If | |
1126 | +** The btree balancer needs additional memory beyond what is provided by | |
1127 | +** scratch buffers or if no scratch buffer space is specified, then SQLite | |
1128 | +** goes to [sqlite3_malloc()] to obtain the memory it needs.</dd> | |
1129 | +** | |
1130 | +** <dt>SQLITE_CONFIG_PAGECACHE</dt> | |
1131 | +** <dd>This option specifies a static memory buffer that SQLite can use for | |
1132 | +** the database page cache with the default page cache implemenation. | |
1133 | +** This configuration should not be used if an application-define page | |
1134 | +** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option. | |
1135 | +** There are three arguments to this option: A pointer to 8-byte aligned | |
1136 | +** memory, the size of each page buffer (sz), and the number of pages (N). | |
1137 | +** The sz argument should be the size of the largest database page | |
1138 | +** (a power of two between 512 and 32768) plus a little extra for each | |
1139 | +** page header. The page header size is 20 to 40 bytes depending on | |
1140 | +** the host architecture. It is harmless, apart from the wasted memory, | |
1141 | +** to make sz a little too large. The first | |
1142 | +** argument should point to an allocation of at least sz*N bytes of memory. | |
1143 | +** SQLite will use the memory provided by the first argument to satisfy its | |
1144 | +** memory needs for the first N pages that it adds to cache. If additional | |
1145 | +** page cache memory is needed beyond what is provided by this option, then | |
1146 | +** SQLite goes to [sqlite3_malloc()] for the additional storage space. | |
1147 | +** The implementation might use one or more of the N buffers to hold | |
1148 | +** memory accounting information. The pointer in the first argument must | |
1149 | +** be aligned to an 8-byte boundary or subsequent behavior of SQLite | |
1150 | +** will be undefined.</dd> | |
1151 | +** | |
1152 | +** <dt>SQLITE_CONFIG_HEAP</dt> | |
1153 | +** <dd>This option specifies a static memory buffer that SQLite will use | |
1154 | +** for all of its dynamic memory allocation needs beyond those provided | |
1155 | +** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE]. | |
1156 | +** There are three arguments: An 8-byte aligned pointer to the memory, | |
1157 | +** the number of bytes in the memory buffer, and the minimum allocation size. | |
1158 | +** If the first pointer (the memory pointer) is NULL, then SQLite reverts | |
1159 | +** to using its default memory allocator (the system malloc() implementation), | |
1160 | +** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. If the | |
1161 | +** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or | |
1162 | +** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory | |
1163 | +** allocator is engaged to handle all of SQLites memory allocation needs. | |
1164 | +** The first pointer (the memory pointer) must be aligned to an 8-byte | |
1165 | +** boundary or subsequent behavior of SQLite will be undefined.</dd> | |
1166 | +** | |
1167 | +** <dt>SQLITE_CONFIG_MUTEX</dt> | |
1168 | +** <dd>This option takes a single argument which is a pointer to an | |
1169 | +** instance of the [sqlite3_mutex_methods] structure. The argument specifies | |
1170 | +** alternative low-level mutex routines to be used in place | |
1171 | +** the mutex routines built into SQLite.</dd> | |
1172 | +** | |
1173 | +** <dt>SQLITE_CONFIG_GETMUTEX</dt> | |
1174 | +** <dd>This option takes a single argument which is a pointer to an | |
1175 | +** instance of the [sqlite3_mutex_methods] structure. The | |
1176 | +** [sqlite3_mutex_methods] | |
1177 | +** structure is filled with the currently defined mutex routines. | |
1178 | +** This option can be used to overload the default mutex allocation | |
1179 | +** routines with a wrapper used to track mutex usage for performance | |
1180 | +** profiling or testing, for example.</dd> | |
1181 | +** | |
1182 | +** <dt>SQLITE_CONFIG_LOOKASIDE</dt> | |
1183 | +** <dd>This option takes two arguments that determine the default | |
1184 | +** memory allocation lookaside optimization. The first argument is the | |
1185 | +** size of each lookaside buffer slot and the second is the number of | |
1186 | +** slots allocated to each database connection. This option sets the | |
1187 | +** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE] | |
1188 | +** verb to [sqlite3_db_config()] can be used to change the lookaside | |
1189 | +** configuration on individual connections.</dd> | |
1190 | +** | |
1191 | +** <dt>SQLITE_CONFIG_PCACHE</dt> | |
1192 | +** <dd>This option takes a single argument which is a pointer to | |
1193 | +** an [sqlite3_pcache_methods] object. This object specifies the interface | |
1194 | +** to a custom page cache implementation. SQLite makes a copy of the | |
1195 | +** object and uses it for page cache memory allocations.</dd> | |
1196 | +** | |
1197 | +** <dt>SQLITE_CONFIG_GETPCACHE</dt> | |
1198 | +** <dd>This option takes a single argument which is a pointer to an | |
1199 | +** [sqlite3_pcache_methods] object. SQLite copies of the current | |
1200 | +** page cache implementation into that object.</dd> | |
1201 | +** | |
1202 | +** </dl> | |
1203 | +*/ | |
1204 | +#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ | |
1205 | +#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ | |
1206 | +#define SQLITE_CONFIG_SERIALIZED 3 /* nil */ | |
1207 | +#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */ | |
1208 | +#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */ | |
1209 | +#define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */ | |
1210 | +#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ | |
1211 | +#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ | |
1212 | +#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ | |
1213 | +#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ | |
1214 | +#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ | |
1215 | +/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ | |
1216 | +#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */ | |
1217 | +#define SQLITE_CONFIG_PCACHE 14 /* sqlite3_pcache_methods* */ | |
1218 | +#define SQLITE_CONFIG_GETPCACHE 15 /* sqlite3_pcache_methods* */ | |
1219 | + | |
1220 | +/* | |
1221 | +** CAPI3REF: Configuration Options {H10170} <S20000> | |
1222 | +** EXPERIMENTAL | |
1223 | +** | |
1224 | +** These constants are the available integer configuration options that | |
1225 | +** can be passed as the second argument to the [sqlite3_db_config()] interface. | |
1226 | +** | |
1227 | +** New configuration options may be added in future releases of SQLite. | |
1228 | +** Existing configuration options might be discontinued. Applications | |
1229 | +** should check the return code from [sqlite3_db_config()] to make sure that | |
1230 | +** the call worked. The [sqlite3_db_config()] interface will return a | |
1231 | +** non-zero [error code] if a discontinued or unsupported configuration option | |
1232 | +** is invoked. | |
1233 | +** | |
1234 | +** <dl> | |
1235 | +** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt> | |
1236 | +** <dd>This option takes three additional arguments that determine the | |
1237 | +** [lookaside memory allocator] configuration for the [database connection]. | |
1238 | +** The first argument (the third parameter to [sqlite3_db_config()] is a | |
1239 | +** pointer to an memory buffer to use for lookaside memory. | |
1240 | +** The first argument may be NULL in which case SQLite will allocate the | |
1241 | +** lookaside buffer itself using [sqlite3_malloc()]. The second argument is the | |
1242 | +** size of each lookaside buffer slot and the third argument is the number of | |
1243 | +** slots. The size of the buffer in the first argument must be greater than | |
1244 | +** or equal to the product of the second and third arguments. The buffer | |
1245 | +** must be aligned to an 8-byte boundary. If the second argument is not | |
1246 | +** a multiple of 8, it is internally rounded down to the next smaller | |
1247 | +** multiple of 8. See also: [SQLITE_CONFIG_LOOKASIDE]</dd> | |
1248 | +** | |
1249 | +** </dl> | |
1250 | +*/ | |
1251 | +#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ | |
1252 | + | |
1253 | + | |
1254 | +/* | |
1255 | +** CAPI3REF: Enable Or Disable Extended Result Codes {H12200} <S10700> | |
1256 | +** | |
1257 | +** The sqlite3_extended_result_codes() routine enables or disables the | |
1258 | +** [extended result codes] feature of SQLite. The extended result | |
1259 | +** codes are disabled by default for historical compatibility considerations. | |
1260 | +** | |
1261 | +** Requirements: | |
1262 | +** [H12201] [H12202] | |
1263 | +*/ | |
1264 | +SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff); | |
1265 | + | |
1266 | +/* | |
1267 | +** CAPI3REF: Last Insert Rowid {H12220} <S10700> | |
1268 | +** | |
1269 | +** Each entry in an SQLite table has a unique 64-bit signed | |
1270 | +** integer key called the [ROWID | "rowid"]. The rowid is always available | |
1271 | +** as an undeclared column named ROWID, OID, or _ROWID_ as long as those | |
1272 | +** names are not also used by explicitly declared columns. If | |
1273 | +** the table has a column of type [INTEGER PRIMARY KEY] then that column | |
1274 | +** is another alias for the rowid. | |
1275 | +** | |
1276 | +** This routine returns the [rowid] of the most recent | |
1277 | +** successful [INSERT] into the database from the [database connection] | |
1278 | +** in the first argument. If no successful [INSERT]s | |
1279 | +** have ever occurred on that database connection, zero is returned. | |
1280 | +** | |
1281 | +** If an [INSERT] occurs within a trigger, then the [rowid] of the inserted | |
1282 | +** row is returned by this routine as long as the trigger is running. | |
1283 | +** But once the trigger terminates, the value returned by this routine | |
1284 | +** reverts to the last value inserted before the trigger fired. | |
1285 | +** | |
1286 | +** An [INSERT] that fails due to a constraint violation is not a | |
1287 | +** successful [INSERT] and does not change the value returned by this | |
1288 | +** routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK, | |
1289 | +** and INSERT OR ABORT make no changes to the return value of this | |
1290 | +** routine when their insertion fails. When INSERT OR REPLACE | |
1291 | +** encounters a constraint violation, it does not fail. The | |
1292 | +** INSERT continues to completion after deleting rows that caused | |
1293 | +** the constraint problem so INSERT OR REPLACE will always change | |
1294 | +** the return value of this interface. | |
1295 | +** | |
1296 | +** For the purposes of this routine, an [INSERT] is considered to | |
1297 | +** be successful even if it is subsequently rolled back. | |
1298 | +** | |
1299 | +** Requirements: | |
1300 | +** [H12221] [H12223] | |
1301 | +** | |
1302 | +** If a separate thread performs a new [INSERT] on the same | |
1303 | +** database connection while the [sqlite3_last_insert_rowid()] | |
1304 | +** function is running and thus changes the last insert [rowid], | |
1305 | +** then the value returned by [sqlite3_last_insert_rowid()] is | |
1306 | +** unpredictable and might not equal either the old or the new | |
1307 | +** last insert [rowid]. | |
1308 | +*/ | |
1309 | +SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); | |
1310 | + | |
1311 | +/* | |
1312 | +** CAPI3REF: Count The Number Of Rows Modified {H12240} <S10600> | |
349 | 1313 | ** |
350 | 1314 | ** This function returns the number of database rows that were changed |
351 | -** (or inserted or deleted) by the most recent SQL statement. Only | |
352 | -** changes that are directly specified by the INSERT, UPDATE, or | |
353 | -** DELETE statement are counted. Auxiliary changes caused by | |
354 | -** triggers are not counted. Use the [sqlite3_total_changes()] function | |
1315 | +** or inserted or deleted by the most recently completed SQL statement | |
1316 | +** on the [database connection] specified by the first parameter. | |
1317 | +** Only changes that are directly specified by the [INSERT], [UPDATE], | |
1318 | +** or [DELETE] statement are counted. Auxiliary changes caused by | |
1319 | +** triggers are not counted. Use the [sqlite3_total_changes()] function | |
355 | 1320 | ** to find the total number of changes including changes caused by triggers. |
356 | 1321 | ** |
357 | -** Within the body of a trigger, the sqlite3_changes() interface can be | |
358 | -** called to find the number of | |
1322 | +** Changes to a view that are simulated by an [INSTEAD OF trigger] | |
1323 | +** are not counted. Only real table changes are counted. | |
1324 | +** | |
1325 | +** A "row change" is a change to a single row of a single table | |
1326 | +** caused by an INSERT, DELETE, or UPDATE statement. Rows that | |
1327 | +** are changed as side effects of [REPLACE] constraint resolution, | |
1328 | +** rollback, ABORT processing, [DROP TABLE], or by any other | |
1329 | +** mechanisms do not count as direct row changes. | |
1330 | +** | |
1331 | +** A "trigger context" is a scope of execution that begins and | |
1332 | +** ends with the script of a [CREATE TRIGGER | trigger]. | |
1333 | +** Most SQL statements are | |
1334 | +** evaluated outside of any trigger. This is the "top level" | |
1335 | +** trigger context. If a trigger fires from the top level, a | |
1336 | +** new trigger context is entered for the duration of that one | |
1337 | +** trigger. Subtriggers create subcontexts for their duration. | |
1338 | +** | |
1339 | +** Calling [sqlite3_exec()] or [sqlite3_step()] recursively does | |
1340 | +** not create a new trigger context. | |
1341 | +** | |
1342 | +** This function returns the number of direct row changes in the | |
1343 | +** most recent INSERT, UPDATE, or DELETE statement within the same | |
1344 | +** trigger context. | |
1345 | +** | |
1346 | +** Thus, when called from the top level, this function returns the | |
1347 | +** number of changes in the most recent INSERT, UPDATE, or DELETE | |
1348 | +** that also occurred at the top level. Within the body of a trigger, | |
1349 | +** the sqlite3_changes() interface can be called to find the number of | |
359 | 1350 | ** changes in the most recently completed INSERT, UPDATE, or DELETE |
360 | -** statement within the body of the trigger. | |
1351 | +** statement within the body of the same trigger. | |
1352 | +** However, the number returned does not include changes | |
1353 | +** caused by subtriggers since those have their own context. | |
361 | 1354 | ** |
362 | -** All changes are counted, even if they were later undone by a | |
363 | -** ROLLBACK or ABORT. Except, changes associated with creating and | |
364 | -** dropping tables are not counted. | |
1355 | +** See also the [sqlite3_total_changes()] interface and the | |
1356 | +** [count_changes pragma]. | |
365 | 1357 | ** |
366 | -** If a callback invokes [sqlite3_exec()] or [sqlite3_step()] recursively, | |
367 | -** then the changes in the inner, recursive call are counted together | |
368 | -** with the changes in the outer call. | |
1358 | +** Requirements: | |
1359 | +** [H12241] [H12243] | |
369 | 1360 | ** |
370 | -** SQLite implements the command "DELETE FROM table" without a WHERE clause | |
371 | -** by dropping and recreating the table. (This is much faster than going | |
372 | -** through and deleting individual elements from the table.) Because of | |
373 | -** this optimization, the change count for "DELETE FROM table" will be | |
374 | -** zero regardless of the number of elements that were originally in the | |
375 | -** table. To get an accurate count of the number of rows deleted, use | |
376 | -** "DELETE FROM table WHERE 1" instead. | |
1361 | +** If a separate thread makes changes on the same database connection | |
1362 | +** while [sqlite3_changes()] is running then the value returned | |
1363 | +** is unpredictable and not meaningful. | |
377 | 1364 | */ |
378 | -int sqlite3_changes(sqlite3*); | |
1365 | +SQLITE_API int sqlite3_changes(sqlite3*); | |
379 | 1366 | |
380 | 1367 | /* |
381 | -** CAPI3REF: Total Number Of Rows Modified | |
382 | -*** | |
383 | -** This function returns the number of database rows that have been | |
384 | -** modified by INSERT, UPDATE or DELETE statements since the database handle | |
385 | -** was opened. This includes UPDATE, INSERT and DELETE statements executed | |
386 | -** as part of trigger programs. All changes are counted as soon as the | |
387 | -** statement that makes them is completed (when the statement handle is | |
388 | -** passed to [sqlite3_reset()] or [sqlite_finalise()]). | |
389 | -** | |
390 | -** See also the [sqlite3_change()] interface. | |
391 | -** | |
392 | -** SQLite implements the command "DELETE FROM table" without a WHERE clause | |
393 | -** by dropping and recreating the table. (This is much faster than going | |
394 | -** through and deleting individual elements form the table.) Because of | |
395 | -** this optimization, the change count for "DELETE FROM table" will be | |
396 | -** zero regardless of the number of elements that were originally in the | |
397 | -** table. To get an accurate count of the number of rows deleted, use | |
398 | -** "DELETE FROM table WHERE 1" instead. | |
1368 | +** CAPI3REF: Total Number Of Rows Modified {H12260} <S10600> | |
1369 | +** | |
1370 | +** This function returns the number of row changes caused by [INSERT], | |
1371 | +** [UPDATE] or [DELETE] statements since the [database connection] was opened. | |
1372 | +** The count includes all changes from all | |
1373 | +** [CREATE TRIGGER | trigger] contexts. However, | |
1374 | +** the count does not include changes used to implement [REPLACE] constraints, | |
1375 | +** do rollbacks or ABORT processing, or [DROP TABLE] processing. The | |
1376 | +** count does not include rows of views that fire an [INSTEAD OF trigger], | |
1377 | +** though if the INSTEAD OF trigger makes changes of its own, those changes | |
1378 | +** are counted. | |
1379 | +** The changes are counted as soon as the statement that makes them is | |
1380 | +** completed (when the statement handle is passed to [sqlite3_reset()] or | |
1381 | +** [sqlite3_finalize()]). | |
1382 | +** | |
1383 | +** See also the [sqlite3_changes()] interface and the | |
1384 | +** [count_changes pragma]. | |
1385 | +** | |
1386 | +** Requirements: | |
1387 | +** [H12261] [H12263] | |
1388 | +** | |
1389 | +** If a separate thread makes changes on the same database connection | |
1390 | +** while [sqlite3_total_changes()] is running then the value | |
1391 | +** returned is unpredictable and not meaningful. | |
399 | 1392 | */ |
400 | -int sqlite3_total_changes(sqlite3*); | |
1393 | +SQLITE_API int sqlite3_total_changes(sqlite3*); | |
401 | 1394 | |
402 | 1395 | /* |
403 | -** CAPI3REF: Interrupt A Long-Running Query | |
1396 | +** CAPI3REF: Interrupt A Long-Running Query {H12270} <S30500> | |
404 | 1397 | ** |
405 | 1398 | ** This function causes any pending database operation to abort and |
406 | -** return at its earliest opportunity. This routine is typically | |
1399 | +** return at its earliest opportunity. This routine is typically | |
407 | 1400 | ** called in response to a user action such as pressing "Cancel" |
408 | 1401 | ** or Ctrl-C where the user wants a long query operation to halt |
409 | 1402 | ** immediately. |
410 | 1403 | ** |
411 | 1404 | ** It is safe to call this routine from a thread different from the |
412 | -** thread that is currently running the database operation. | |
413 | -** | |
414 | -** The SQL operation that is interrupted will return [SQLITE_INTERRUPT]. | |
415 | -** If an interrupted operation was an update that is inside an | |
416 | -** explicit transaction, then the entire transaction will be rolled | |
417 | -** back automatically. | |
418 | -*/ | |
419 | -void sqlite3_interrupt(sqlite3*); | |
420 | - | |
421 | -/* | |
422 | -** CAPI3REF: Determine If An SQL Statement Is Complete | |
423 | -** | |
424 | -** These functions return true if the given input string comprises | |
425 | -** one or more complete SQL statements. For the sqlite3_complete() call, | |
426 | -** the parameter must be a nul-terminated UTF-8 string. For | |
427 | -** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string | |
428 | -** is required. | |
429 | -** | |
430 | -** These routines are useful for command-line input to determine if the | |
431 | -** currently entered text forms one or more complete SQL statements or | |
432 | -** if additional input is needed before sending the statements into | |
433 | -** SQLite for parsing. The algorithm is simple. If the | |
434 | -** last token other than spaces and comments is a semicolon, then return | |
435 | -** true. Actually, the algorithm is a little more complicated than that | |
436 | -** in order to deal with triggers, but the basic idea is the same: the | |
437 | -** statement is not complete unless it ends in a semicolon. | |
438 | -*/ | |
439 | -int sqlite3_complete(const char *sql); | |
440 | -int sqlite3_complete16(const void *sql); | |
441 | - | |
442 | -/* | |
443 | -** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors | |
444 | -** | |
445 | -** This routine identifies a callback function that might be invoked | |
446 | -** whenever an attempt is made to open a database table | |
447 | -** that another thread or process has locked. | |
448 | -** If the busy callback is NULL, then [SQLITE_BUSY] | |
449 | -** (or sometimes [SQLITE_IOERR_BLOCKED]) | |
450 | -** is returned immediately upon encountering the lock. | |
451 | -** If the busy callback is not NULL, then the | |
452 | -** callback will be invoked with two arguments. The | |
453 | -** first argument to the handler is a copy of the void* pointer which | |
454 | -** is the third argument to this routine. The second argument to | |
455 | -** the handler is the number of times that the busy handler has | |
456 | -** been invoked for this locking event. If the | |
1405 | +** thread that is currently running the database operation. But it | |
1406 | +** is not safe to call this routine with a [database connection] that | |
1407 | +** is closed or might close before sqlite3_interrupt() returns. | |
1408 | +** | |
1409 | +** If an SQL operation is very nearly finished at the time when | |
1410 | +** sqlite3_interrupt() is called, then it might not have an opportunity | |
1411 | +** to be interrupted and might continue to completion. | |
1412 | +** | |
1413 | +** An SQL operation that is interrupted will return [SQLITE_INTERRUPT]. | |
1414 | +** If the interrupted SQL operation is an INSERT, UPDATE, or DELETE | |
1415 | +** that is inside an explicit transaction, then the entire transaction | |
1416 | +** will be rolled back automatically. | |
1417 | +** | |
1418 | +** The sqlite3_interrupt(D) call is in effect until all currently running | |
1419 | +** SQL statements on [database connection] D complete. Any new SQL statements | |
1420 | +** that are started after the sqlite3_interrupt() call and before the | |
1421 | +** running statements reaches zero are interrupted as if they had been | |
1422 | +** running prior to the sqlite3_interrupt() call. New SQL statements | |
1423 | +** that are started after the running statement count reaches zero are | |
1424 | +** not effected by the sqlite3_interrupt(). | |
1425 | +** A call to sqlite3_interrupt(D) that occurs when there are no running | |
1426 | +** SQL statements is a no-op and has no effect on SQL statements | |
1427 | +** that are started after the sqlite3_interrupt() call returns. | |
1428 | +** | |
1429 | +** Requirements: | |
1430 | +** [H12271] [H12272] | |
1431 | +** | |
1432 | +** If the database connection closes while [sqlite3_interrupt()] | |
1433 | +** is running then bad things will likely happen. | |
1434 | +*/ | |
1435 | +SQLITE_API void sqlite3_interrupt(sqlite3*); | |
1436 | + | |
1437 | +/* | |
1438 | +** CAPI3REF: Determine If An SQL Statement Is Complete {H10510} <S70200> | |
1439 | +** | |
1440 | +** These routines are useful during command-line input to determine if the | |
1441 | +** currently entered text seems to form a complete SQL statement or | |
1442 | +** if additional input is needed before sending the text into | |
1443 | +** SQLite for parsing. These routines return 1 if the input string | |
1444 | +** appears to be a complete SQL statement. A statement is judged to be | |
1445 | +** complete if it ends with a semicolon token and is not a prefix of a | |
1446 | +** well-formed CREATE TRIGGER statement. Semicolons that are embedded within | |
1447 | +** string literals or quoted identifier names or comments are not | |
1448 | +** independent tokens (they are part of the token in which they are | |
1449 | +** embedded) and thus do not count as a statement terminator. Whitespace | |
1450 | +** and comments that follow the final semicolon are ignored. | |
1451 | +** | |
1452 | +** These routines return 0 if the statement is incomplete. If a | |
1453 | +** memory allocation fails, then SQLITE_NOMEM is returned. | |
1454 | +** | |
1455 | +** These routines do not parse the SQL statements thus | |
1456 | +** will not detect syntactically incorrect SQL. | |
1457 | +** | |
1458 | +** If SQLite has not been initialized using [sqlite3_initialize()] prior | |
1459 | +** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked | |
1460 | +** automatically by sqlite3_complete16(). If that initialization fails, | |
1461 | +** then the return value from sqlite3_complete16() will be non-zero | |
1462 | +** regardless of whether or not the input SQL is complete. | |
1463 | +** | |
1464 | +** Requirements: [H10511] [H10512] | |
1465 | +** | |
1466 | +** The input to [sqlite3_complete()] must be a zero-terminated | |
1467 | +** UTF-8 string. | |
1468 | +** | |
1469 | +** The input to [sqlite3_complete16()] must be a zero-terminated | |
1470 | +** UTF-16 string in native byte order. | |
1471 | +*/ | |
1472 | +SQLITE_API int sqlite3_complete(const char *sql); | |
1473 | +SQLITE_API int sqlite3_complete16(const void *sql); | |
1474 | + | |
1475 | +/* | |
1476 | +** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {H12310} <S40400> | |
1477 | +** | |
1478 | +** This routine sets a callback function that might be invoked whenever | |
1479 | +** an attempt is made to open a database table that another thread | |
1480 | +** or process has locked. | |
1481 | +** | |
1482 | +** If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] | |
1483 | +** is returned immediately upon encountering the lock. If the busy callback | |
1484 | +** is not NULL, then the callback will be invoked with two arguments. | |
1485 | +** | |
1486 | +** The first argument to the handler is a copy of the void* pointer which | |
1487 | +** is the third argument to sqlite3_busy_handler(). The second argument to | |
1488 | +** the handler callback is the number of times that the busy handler has | |
1489 | +** been invoked for this locking event. If the | |
457 | 1490 | ** busy callback returns 0, then no additional attempts are made to |
458 | 1491 | ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned. |
459 | -** If the callback returns non-zero, then another attempt is made to open the | |
460 | -** database for reading and the cycle repeats. | |
1492 | +** If the callback returns non-zero, then another attempt | |
1493 | +** is made to open the database for reading and the cycle repeats. | |
461 | 1494 | ** |
462 | -** The presence of a busy handler does not guarantee that | |
463 | -** it will be invoked when there is lock contention. | |
464 | -** If SQLite determines that invoking the busy handler could result in | |
465 | -** a deadlock, it will return [SQLITE_BUSY] instead. | |
1495 | +** The presence of a busy handler does not guarantee that it will be invoked | |
1496 | +** when there is lock contention. If SQLite determines that invoking the busy | |
1497 | +** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY] | |
1498 | +** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler. | |
466 | 1499 | ** Consider a scenario where one process is holding a read lock that |
467 | 1500 | ** it is trying to promote to a reserved lock and |
468 | 1501 | ** a second process is holding a reserved lock that it is trying |
@@ -476,8 +1509,8 @@ int sqlite3_complete16(const void *sql); | ||
476 | 1509 | ** |
477 | 1510 | ** The default busy callback is NULL. |
478 | 1511 | ** |
479 | -** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] when | |
480 | -** SQLite is in the middle of a large transaction where all the | |
1512 | +** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] | |
1513 | +** when SQLite is in the middle of a large transaction where all the | |
481 | 1514 | ** changes will not fit into the in-memory cache. SQLite will |
482 | 1515 | ** already hold a RESERVED lock on the database file, but it needs |
483 | 1516 | ** to promote this lock to EXCLUSIVE so that it can spill cache |
@@ -486,109 +1519,140 @@ int sqlite3_complete16(const void *sql); | ||
486 | 1519 | ** cache will be left in an inconsistent state and so the error |
487 | 1520 | ** code is promoted from the relatively benign [SQLITE_BUSY] to |
488 | 1521 | ** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion |
489 | -** forces an automatic rollback of the changes. See the | |
490 | -** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError"> | |
1522 | +** forces an automatic rollback of the changes. See the | |
1523 | +** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError"> | |
491 | 1524 | ** CorruptionFollowingBusyError</a> wiki page for a discussion of why |
492 | 1525 | ** this is important. |
493 | -** | |
494 | -** Sqlite is re-entrant, so the busy handler may start a new query. | |
495 | -** (It is not clear why anyone would every want to do this, but it | |
496 | -** is allowed, in theory.) But the busy handler may not close the | |
497 | -** database. Closing the database from a busy handler will delete | |
498 | -** data structures out from under the executing query and will | |
499 | -** probably result in a segmentation fault or other runtime error. | |
500 | 1526 | ** |
501 | -** There can only be a single busy handler defined for each database | |
502 | -** connection. Setting a new busy handler clears any previous one. | |
503 | -** Note that calling [sqlite3_busy_timeout()] will also set or clear | |
504 | -** the busy handler. | |
1527 | +** There can only be a single busy handler defined for each | |
1528 | +** [database connection]. Setting a new busy handler clears any | |
1529 | +** previously set handler. Note that calling [sqlite3_busy_timeout()] | |
1530 | +** will also set or clear the busy handler. | |
1531 | +** | |
1532 | +** The busy callback should not take any actions which modify the | |
1533 | +** database connection that invoked the busy handler. Any such actions | |
1534 | +** result in undefined behavior. | |
1535 | +** | |
1536 | +** Requirements: | |
1537 | +** [H12311] [H12312] [H12314] [H12316] [H12318] | |
1538 | +** | |
1539 | +** A busy handler must not close the database connection | |
1540 | +** or [prepared statement] that invoked the busy handler. | |
505 | 1541 | */ |
506 | -int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); | |
1542 | +SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); | |
507 | 1543 | |
508 | 1544 | /* |
509 | -** CAPI3REF: Set A Busy Timeout | |
1545 | +** CAPI3REF: Set A Busy Timeout {H12340} <S40410> | |
510 | 1546 | ** |
511 | -** This routine sets a busy handler that sleeps for a while when a | |
512 | -** table is locked. The handler will sleep multiple times until | |
513 | -** at least "ms" milliseconds of sleeping have been done. After | |
514 | -** "ms" milliseconds of sleeping, the handler returns 0 which | |
515 | -** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. | |
1547 | +** This routine sets a [sqlite3_busy_handler | busy handler] that sleeps | |
1548 | +** for a specified amount of time when a table is locked. The handler | |
1549 | +** will sleep multiple times until at least "ms" milliseconds of sleeping | |
1550 | +** have accumulated. {H12343} After "ms" milliseconds of sleeping, | |
1551 | +** the handler returns 0 which causes [sqlite3_step()] to return | |
1552 | +** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. | |
516 | 1553 | ** |
517 | 1554 | ** Calling this routine with an argument less than or equal to zero |
518 | 1555 | ** turns off all busy handlers. |
519 | 1556 | ** |
520 | -** There can only be a single busy handler for a particular database | |
521 | -** connection. If another busy handler was defined | |
522 | -** (using [sqlite3_busy_handler()]) prior to calling | |
1557 | +** There can only be a single busy handler for a particular | |
1558 | +** [database connection] any any given moment. If another busy handler | |
1559 | +** was defined (using [sqlite3_busy_handler()]) prior to calling | |
523 | 1560 | ** this routine, that other busy handler is cleared. |
1561 | +** | |
1562 | +** Requirements: | |
1563 | +** [H12341] [H12343] [H12344] | |
524 | 1564 | */ |
525 | -int sqlite3_busy_timeout(sqlite3*, int ms); | |
1565 | +SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms); | |
526 | 1566 | |
527 | 1567 | /* |
528 | -** CAPI3REF: Convenience Routines For Running Queries | |
1568 | +** CAPI3REF: Convenience Routines For Running Queries {H12370} <S10000> | |
529 | 1569 | ** |
530 | -** This next routine is a convenience wrapper around [sqlite3_exec()]. | |
531 | -** Instead of invoking a user-supplied callback for each row of the | |
532 | -** result, this routine remembers each row of the result in memory | |
533 | -** obtained from [sqlite3_malloc()], then returns all of the result after the | |
534 | -** query has finished. | |
1570 | +** Definition: A <b>result table</b> is memory data structure created by the | |
1571 | +** [sqlite3_get_table()] interface. A result table records the | |
1572 | +** complete query results from one or more queries. | |
535 | 1573 | ** |
536 | -** As an example, suppose the query result where this table: | |
1574 | +** The table conceptually has a number of rows and columns. But | |
1575 | +** these numbers are not part of the result table itself. These | |
1576 | +** numbers are obtained separately. Let N be the number of rows | |
1577 | +** and M be the number of columns. | |
537 | 1578 | ** |
538 | -** <pre> | |
1579 | +** A result table is an array of pointers to zero-terminated UTF-8 strings. | |
1580 | +** There are (N+1)*M elements in the array. The first M pointers point | |
1581 | +** to zero-terminated strings that contain the names of the columns. | |
1582 | +** The remaining entries all point to query results. NULL values result | |
1583 | +** in NULL pointers. All other values are in their UTF-8 zero-terminated | |
1584 | +** string representation as returned by [sqlite3_column_text()]. | |
1585 | +** | |
1586 | +** A result table might consist of one or more memory allocations. | |
1587 | +** It is not safe to pass a result table directly to [sqlite3_free()]. | |
1588 | +** A result table should be deallocated using [sqlite3_free_table()]. | |
1589 | +** | |
1590 | +** As an example of the result table format, suppose a query result | |
1591 | +** is as follows: | |
1592 | +** | |
1593 | +** <blockquote><pre> | |
539 | 1594 | ** Name | Age |
540 | 1595 | ** ----------------------- |
541 | 1596 | ** Alice | 43 |
542 | 1597 | ** Bob | 28 |
543 | 1598 | ** Cindy | 21 |
544 | -** </pre> | |
1599 | +** </pre></blockquote> | |
545 | 1600 | ** |
546 | -** If the 3rd argument were &azResult then after the function returns | |
547 | -** azResult will contain the following data: | |
1601 | +** There are two column (M==2) and three rows (N==3). Thus the | |
1602 | +** result table has 8 entries. Suppose the result table is stored | |
1603 | +** in an array names azResult. Then azResult holds this content: | |
548 | 1604 | ** |
549 | -** <pre> | |
550 | -** azResult[0] = "Name"; | |
551 | -** azResult[1] = "Age"; | |
552 | -** azResult[2] = "Alice"; | |
553 | -** azResult[3] = "43"; | |
554 | -** azResult[4] = "Bob"; | |
555 | -** azResult[5] = "28"; | |
556 | -** azResult[6] = "Cindy"; | |
557 | -** azResult[7] = "21"; | |
558 | -** </pre> | |
1605 | +** <blockquote><pre> | |
1606 | +** azResult[0] = "Name"; | |
1607 | +** azResult[1] = "Age"; | |
1608 | +** azResult[2] = "Alice"; | |
1609 | +** azResult[3] = "43"; | |
1610 | +** azResult[4] = "Bob"; | |
1611 | +** azResult[5] = "28"; | |
1612 | +** azResult[6] = "Cindy"; | |
1613 | +** azResult[7] = "21"; | |
1614 | +** </pre></blockquote> | |
559 | 1615 | ** |
560 | -** Notice that there is an extra row of data containing the column | |
561 | -** headers. But the *nrow return value is still 3. *ncolumn is | |
562 | -** set to 2. In general, the number of values inserted into azResult | |
563 | -** will be ((*nrow) + 1)*(*ncolumn). | |
564 | -** | |
565 | -** After the calling function has finished using the result, it should | |
566 | -** pass the result data pointer to sqlite3_free_table() in order to | |
567 | -** release the memory that was malloc-ed. Because of the way the | |
568 | -** [sqlite3_malloc()] happens, the calling function must not try to call | |
569 | -** [sqlite3_free()] directly. Only [sqlite3_free_table()] is able to release | |
570 | -** the memory properly and safely. | |
571 | -** | |
572 | -** The return value of this routine is the same as from [sqlite3_exec()]. | |
573 | -*/ | |
574 | -int sqlite3_get_table( | |
575 | - sqlite3*, /* An open database */ | |
576 | - const char *sql, /* SQL to be executed */ | |
577 | - char ***resultp, /* Result written to a char *[] that this points to */ | |
578 | - int *nrow, /* Number of result rows written here */ | |
579 | - int *ncolumn, /* Number of result columns written here */ | |
580 | - char **errmsg /* Error msg written here */ | |
1616 | +** The sqlite3_get_table() function evaluates one or more | |
1617 | +** semicolon-separated SQL statements in the zero-terminated UTF-8 | |
1618 | +** string of its 2nd parameter. It returns a result table to the | |
1619 | +** pointer given in its 3rd parameter. | |
1620 | +** | |
1621 | +** After the calling function has finished using the result, it should | |
1622 | +** pass the pointer to the result table to sqlite3_free_table() in order to | |
1623 | +** release the memory that was malloced. Because of the way the | |
1624 | +** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling | |
1625 | +** function must not try to call [sqlite3_free()] directly. Only | |
1626 | +** [sqlite3_free_table()] is able to release the memory properly and safely. | |
1627 | +** | |
1628 | +** The sqlite3_get_table() interface is implemented as a wrapper around | |
1629 | +** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access | |
1630 | +** to any internal data structures of SQLite. It uses only the public | |
1631 | +** interface defined here. As a consequence, errors that occur in the | |
1632 | +** wrapper layer outside of the internal [sqlite3_exec()] call are not | |
1633 | +** reflected in subsequent calls to [sqlite3_errcode()] or [sqlite3_errmsg()]. | |
1634 | +** | |
1635 | +** Requirements: | |
1636 | +** [H12371] [H12373] [H12374] [H12376] [H12379] [H12382] | |
1637 | +*/ | |
1638 | +SQLITE_API int sqlite3_get_table( | |
1639 | + sqlite3 *db, /* An open database */ | |
1640 | + const char *zSql, /* SQL to be evaluated */ | |
1641 | + char ***pazResult, /* Results of the query */ | |
1642 | + int *pnRow, /* Number of result rows written here */ | |
1643 | + int *pnColumn, /* Number of result columns written here */ | |
1644 | + char **pzErrmsg /* Error msg written here */ | |
581 | 1645 | ); |
582 | -void sqlite3_free_table(char **result); | |
1646 | +SQLITE_API void sqlite3_free_table(char **result); | |
583 | 1647 | |
584 | 1648 | /* |
585 | -** CAPI3REF: Formatted String Printing Functions | |
1649 | +** CAPI3REF: Formatted String Printing Functions {H17400} <S70000><S20000> | |
586 | 1650 | ** |
587 | -** These routines are workalikes of the "printf()" family of functions | |
1651 | +** These routines are work-alikes of the "printf()" family of functions | |
588 | 1652 | ** from the standard C library. |
589 | 1653 | ** |
590 | 1654 | ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their |
591 | -** results into memory obtained from [sqlite_malloc()]. | |
1655 | +** results into memory obtained from [sqlite3_malloc()]. | |
592 | 1656 | ** The strings returned by these two routines should be |
593 | 1657 | ** released by [sqlite3_free()]. Both routines return a |
594 | 1658 | ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough |
@@ -597,7 +1661,7 @@ void sqlite3_free_table(char **result); | ||
597 | 1661 | ** In sqlite3_snprintf() routine is similar to "snprintf()" from |
598 | 1662 | ** the standard C library. The result is written into the |
599 | 1663 | ** buffer supplied as the second parameter whose size is given by |
600 | -** the first parameter. Note that the order of the | |
1664 | +** the first parameter. Note that the order of the | |
601 | 1665 | ** first two parameters is reversed from snprintf(). This is an |
602 | 1666 | ** historical accident that cannot be fixed without breaking |
603 | 1667 | ** backwards compatibility. Note also that sqlite3_snprintf() |
@@ -615,8 +1679,8 @@ void sqlite3_free_table(char **result); | ||
615 | 1679 | ** |
616 | 1680 | ** These routines all implement some additional formatting |
617 | 1681 | ** options that are useful for constructing SQL statements. |
618 | -** All of the usual printf formatting options apply. In addition, there | |
619 | -** is are "%q" and "%Q" options. | |
1682 | +** All of the usual printf() formatting options apply. In addition, there | |
1683 | +** is are "%q", "%Q", and "%z" options. | |
620 | 1684 | ** |
621 | 1685 | ** The %q option works like %s in that it substitutes a null-terminated |
622 | 1686 | ** string from the argument list. But %q also doubles every '\'' character. |
@@ -624,7 +1688,7 @@ void sqlite3_free_table(char **result); | ||
624 | 1688 | ** character it escapes that character and allows it to be inserted into |
625 | 1689 | ** the string. |
626 | 1690 | ** |
627 | -** For example, so some string variable contains text as follows: | |
1691 | +** For example, assume the string variable zText contains text as follows: | |
628 | 1692 | ** |
629 | 1693 | ** <blockquote><pre> |
630 | 1694 | ** char *zText = "It's a happy day!"; |
@@ -652,14 +1716,13 @@ void sqlite3_free_table(char **result); | ||
652 | 1716 | ** INSERT INTO table1 VALUES('It's a happy day!'); |
653 | 1717 | ** </pre></blockquote> |
654 | 1718 | ** |
655 | -** This second example is an SQL syntax error. As a general rule you | |
656 | -** should always use %q instead of %s when inserting text into a string | |
657 | -** literal. | |
1719 | +** This second example is an SQL syntax error. As a general rule you should | |
1720 | +** always use %q instead of %s when inserting text into a string literal. | |
658 | 1721 | ** |
659 | 1722 | ** The %Q option works like %q except it also adds single quotes around |
660 | -** the outside of the total string. Or if the parameter in the argument | |
661 | -** list is a NULL pointer, %Q substitutes the text "NULL" (without single | |
662 | -** quotes) in place of the %Q option. So, for example, one could say: | |
1723 | +** the outside of the total string. Additionally, if the parameter in the | |
1724 | +** argument list is a NULL pointer, %Q substitutes the text "NULL" (without | |
1725 | +** single quotes) in place of the %Q option. So, for example, one could say: | |
663 | 1726 | ** |
664 | 1727 | ** <blockquote><pre> |
665 | 1728 | ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText); |
@@ -669,85 +1732,231 @@ void sqlite3_free_table(char **result); | ||
669 | 1732 | ** |
670 | 1733 | ** The code above will render a correct SQL statement in the zSQL |
671 | 1734 | ** variable even if the zText variable is a NULL pointer. |
1735 | +** | |
1736 | +** The "%z" formatting option works exactly like "%s" with the | |
1737 | +** addition that after the string has been read and copied into | |
1738 | +** the result, [sqlite3_free()] is called on the input string. {END} | |
1739 | +** | |
1740 | +** Requirements: | |
1741 | +** [H17403] [H17406] [H17407] | |
1742 | +*/ | |
1743 | +SQLITE_API char *sqlite3_mprintf(const char*,...); | |
1744 | +SQLITE_API char *sqlite3_vmprintf(const char*, va_list); | |
1745 | +SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...); | |
1746 | + | |
1747 | +/* | |
1748 | +** CAPI3REF: Memory Allocation Subsystem {H17300} <S20000> | |
1749 | +** | |
1750 | +** The SQLite core uses these three routines for all of its own | |
1751 | +** internal memory allocation needs. "Core" in the previous sentence | |
1752 | +** does not include operating-system specific VFS implementation. The | |
1753 | +** Windows VFS uses native malloc() and free() for some operations. | |
1754 | +** | |
1755 | +** The sqlite3_malloc() routine returns a pointer to a block | |
1756 | +** of memory at least N bytes in length, where N is the parameter. | |
1757 | +** If sqlite3_malloc() is unable to obtain sufficient free | |
1758 | +** memory, it returns a NULL pointer. If the parameter N to | |
1759 | +** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns | |
1760 | +** a NULL pointer. | |
1761 | +** | |
1762 | +** Calling sqlite3_free() with a pointer previously returned | |
1763 | +** by sqlite3_malloc() or sqlite3_realloc() releases that memory so | |
1764 | +** that it might be reused. The sqlite3_free() routine is | |
1765 | +** a no-op if is called with a NULL pointer. Passing a NULL pointer | |
1766 | +** to sqlite3_free() is harmless. After being freed, memory | |
1767 | +** should neither be read nor written. Even reading previously freed | |
1768 | +** memory might result in a segmentation fault or other severe error. | |
1769 | +** Memory corruption, a segmentation fault, or other severe error | |
1770 | +** might result if sqlite3_free() is called with a non-NULL pointer that | |
1771 | +** was not obtained from sqlite3_malloc() or sqlite3_realloc(). | |
1772 | +** | |
1773 | +** The sqlite3_realloc() interface attempts to resize a | |
1774 | +** prior memory allocation to be at least N bytes, where N is the | |
1775 | +** second parameter. The memory allocation to be resized is the first | |
1776 | +** parameter. If the first parameter to sqlite3_realloc() | |
1777 | +** is a NULL pointer then its behavior is identical to calling | |
1778 | +** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc(). | |
1779 | +** If the second parameter to sqlite3_realloc() is zero or | |
1780 | +** negative then the behavior is exactly the same as calling | |
1781 | +** sqlite3_free(P) where P is the first parameter to sqlite3_realloc(). | |
1782 | +** sqlite3_realloc() returns a pointer to a memory allocation | |
1783 | +** of at least N bytes in size or NULL if sufficient memory is unavailable. | |
1784 | +** If M is the size of the prior allocation, then min(N,M) bytes | |
1785 | +** of the prior allocation are copied into the beginning of buffer returned | |
1786 | +** by sqlite3_realloc() and the prior allocation is freed. | |
1787 | +** If sqlite3_realloc() returns NULL, then the prior allocation | |
1788 | +** is not freed. | |
1789 | +** | |
1790 | +** The memory returned by sqlite3_malloc() and sqlite3_realloc() | |
1791 | +** is always aligned to at least an 8 byte boundary. {END} | |
1792 | +** | |
1793 | +** The default implementation of the memory allocation subsystem uses | |
1794 | +** the malloc(), realloc() and free() provided by the standard C library. | |
1795 | +** {H17382} However, if SQLite is compiled with the | |
1796 | +** SQLITE_MEMORY_SIZE=<i>NNN</i> C preprocessor macro (where <i>NNN</i> | |
1797 | +** is an integer), then SQLite create a static array of at least | |
1798 | +** <i>NNN</i> bytes in size and uses that array for all of its dynamic | |
1799 | +** memory allocation needs. {END} Additional memory allocator options | |
1800 | +** may be added in future releases. | |
1801 | +** | |
1802 | +** In SQLite version 3.5.0 and 3.5.1, it was possible to define | |
1803 | +** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in | |
1804 | +** implementation of these routines to be omitted. That capability | |
1805 | +** is no longer provided. Only built-in memory allocators can be used. | |
1806 | +** | |
1807 | +** The Windows OS interface layer calls | |
1808 | +** the system malloc() and free() directly when converting | |
1809 | +** filenames between the UTF-8 encoding used by SQLite | |
1810 | +** and whatever filename encoding is used by the particular Windows | |
1811 | +** installation. Memory allocation errors are detected, but | |
1812 | +** they are reported back as [SQLITE_CANTOPEN] or | |
1813 | +** [SQLITE_IOERR] rather than [SQLITE_NOMEM]. | |
1814 | +** | |
1815 | +** Requirements: | |
1816 | +** [H17303] [H17304] [H17305] [H17306] [H17310] [H17312] [H17315] [H17318] | |
1817 | +** [H17321] [H17322] [H17323] | |
1818 | +** | |
1819 | +** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] | |
1820 | +** must be either NULL or else pointers obtained from a prior | |
1821 | +** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have | |
1822 | +** not yet been released. | |
1823 | +** | |
1824 | +** The application must not read or write any part of | |
1825 | +** a block of memory after it has been released using | |
1826 | +** [sqlite3_free()] or [sqlite3_realloc()]. | |
672 | 1827 | */ |
673 | -char *sqlite3_mprintf(const char*,...); | |
674 | -char *sqlite3_vmprintf(const char*, va_list); | |
675 | -char *sqlite3_snprintf(int,char*,const char*, ...); | |
1828 | +SQLITE_API void *sqlite3_malloc(int); | |
1829 | +SQLITE_API void *sqlite3_realloc(void*, int); | |
1830 | +SQLITE_API void sqlite3_free(void*); | |
676 | 1831 | |
677 | 1832 | /* |
678 | -** CAPI3REF: Memory Allocation Functions | |
1833 | +** CAPI3REF: Memory Allocator Statistics {H17370} <S30210> | |
679 | 1834 | ** |
680 | -** SQLite uses its own memory allocator. On some installations, this | |
681 | -** memory allocator is identical to the standard malloc()/realloc()/free() | |
682 | -** and can be used interchangable. On others, the implementations are | |
683 | -** different. For maximum portability, it is best not to mix calls | |
684 | -** to the standard malloc/realloc/free with the sqlite versions. | |
1835 | +** SQLite provides these two interfaces for reporting on the status | |
1836 | +** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()] | |
1837 | +** routines, which form the built-in memory allocation subsystem. | |
1838 | +** | |
1839 | +** Requirements: | |
1840 | +** [H17371] [H17373] [H17374] [H17375] | |
685 | 1841 | */ |
686 | -void *sqlite3_malloc(int); | |
687 | -void *sqlite3_realloc(void*, int); | |
688 | -void sqlite3_free(void*); | |
1842 | +SQLITE_API sqlite3_int64 sqlite3_memory_used(void); | |
1843 | +SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag); | |
689 | 1844 | |
690 | 1845 | /* |
691 | -** CAPI3REF: Compile-Time Authorization Callbacks | |
692 | -*** | |
693 | -** This routine registers a authorizer callback with the SQLite library. | |
1846 | +** CAPI3REF: Pseudo-Random Number Generator {H17390} <S20000> | |
1847 | +** | |
1848 | +** SQLite contains a high-quality pseudo-random number generator (PRNG) used to | |
1849 | +** select random [ROWID | ROWIDs] when inserting new records into a table that | |
1850 | +** already uses the largest possible [ROWID]. The PRNG is also used for | |
1851 | +** the build-in random() and randomblob() SQL functions. This interface allows | |
1852 | +** applications to access the same PRNG for other purposes. | |
1853 | +** | |
1854 | +** A call to this routine stores N bytes of randomness into buffer P. | |
1855 | +** | |
1856 | +** The first time this routine is invoked (either internally or by | |
1857 | +** the application) the PRNG is seeded using randomness obtained | |
1858 | +** from the xRandomness method of the default [sqlite3_vfs] object. | |
1859 | +** On all subsequent invocations, the pseudo-randomness is generated | |
1860 | +** internally and without recourse to the [sqlite3_vfs] xRandomness | |
1861 | +** method. | |
1862 | +** | |
1863 | +** Requirements: | |
1864 | +** [H17392] | |
1865 | +*/ | |
1866 | +SQLITE_API void sqlite3_randomness(int N, void *P); | |
1867 | + | |
1868 | +/* | |
1869 | +** CAPI3REF: Compile-Time Authorization Callbacks {H12500} <S70100> | |
1870 | +** | |
1871 | +** This routine registers a authorizer callback with a particular | |
1872 | +** [database connection], supplied in the first argument. | |
694 | 1873 | ** The authorizer callback is invoked as SQL statements are being compiled |
695 | 1874 | ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()], |
696 | 1875 | ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various |
697 | 1876 | ** points during the compilation process, as logic is being created |
698 | 1877 | ** to perform various actions, the authorizer callback is invoked to |
699 | 1878 | ** see if those actions are allowed. The authorizer callback should |
700 | -** return SQLITE_OK to allow the action, [SQLITE_IGNORE] to disallow the | |
1879 | +** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the | |
701 | 1880 | ** specific action but allow the SQL statement to continue to be |
702 | 1881 | ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be |
703 | -** rejected with an error. | |
704 | -** | |
705 | -** Depending on the action, the [SQLITE_IGNORE] and [SQLITE_DENY] return | |
706 | -** codes might mean something different or they might mean the same | |
707 | -** thing. If the action is, for example, to perform a delete opertion, | |
708 | -** then [SQLITE_IGNORE] and [SQLITE_DENY] both cause the statement compilation | |
709 | -** to fail with an error. But if the action is to read a specific column | |
710 | -** from a specific table, then [SQLITE_DENY] will cause the entire | |
711 | -** statement to fail but [SQLITE_IGNORE] will cause a NULL value to be | |
712 | -** read instead of the actual column value. | |
713 | -** | |
714 | -** The first parameter to the authorizer callback is a copy of | |
715 | -** the third parameter to the sqlite3_set_authorizer() interface. | |
716 | -** The second parameter to the callback is an integer | |
717 | -** [SQLITE_COPY | action code] that specifies the particular action | |
718 | -** to be authorized. The available action codes are | |
719 | -** [SQLITE_COPY | documented separately]. The third through sixth | |
720 | -** parameters to the callback are strings that contain additional | |
1882 | +** rejected with an error. If the authorizer callback returns | |
1883 | +** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] | |
1884 | +** then the [sqlite3_prepare_v2()] or equivalent call that triggered | |
1885 | +** the authorizer will fail with an error message. | |
1886 | +** | |
1887 | +** When the callback returns [SQLITE_OK], that means the operation | |
1888 | +** requested is ok. When the callback returns [SQLITE_DENY], the | |
1889 | +** [sqlite3_prepare_v2()] or equivalent call that triggered the | |
1890 | +** authorizer will fail with an error message explaining that | |
1891 | +** access is denied. | |
1892 | +** | |
1893 | +** The first parameter to the authorizer callback is a copy of the third | |
1894 | +** parameter to the sqlite3_set_authorizer() interface. The second parameter | |
1895 | +** to the callback is an integer [SQLITE_COPY | action code] that specifies | |
1896 | +** the particular action to be authorized. The third through sixth parameters | |
1897 | +** to the callback are zero-terminated strings that contain additional | |
721 | 1898 | ** details about the action to be authorized. |
722 | 1899 | ** |
723 | -** An authorizer is used when preparing SQL statements from an untrusted | |
724 | -** source, to ensure that the SQL statements do not try to access data | |
725 | -** that they are not allowed to see, or that they do not try to | |
726 | -** execute malicious statements that damage the database. For | |
1900 | +** If the action code is [SQLITE_READ] | |
1901 | +** and the callback returns [SQLITE_IGNORE] then the | |
1902 | +** [prepared statement] statement is constructed to substitute | |
1903 | +** a NULL value in place of the table column that would have | |
1904 | +** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE] | |
1905 | +** return can be used to deny an untrusted user access to individual | |
1906 | +** columns of a table. | |
1907 | +** If the action code is [SQLITE_DELETE] and the callback returns | |
1908 | +** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the | |
1909 | +** [truncate optimization] is disabled and all rows are deleted individually. | |
1910 | +** | |
1911 | +** An authorizer is used when [sqlite3_prepare | preparing] | |
1912 | +** SQL statements from an untrusted source, to ensure that the SQL statements | |
1913 | +** do not try to access data they are not allowed to see, or that they do not | |
1914 | +** try to execute malicious statements that damage the database. For | |
727 | 1915 | ** example, an application may allow a user to enter arbitrary |
728 | 1916 | ** SQL queries for evaluation by a database. But the application does |
729 | 1917 | ** not want the user to be able to make arbitrary changes to the |
730 | 1918 | ** database. An authorizer could then be put in place while the |
731 | -** user-entered SQL is being prepared that disallows everything | |
732 | -** except SELECT statements. | |
1919 | +** user-entered SQL is being [sqlite3_prepare | prepared] that | |
1920 | +** disallows everything except [SELECT] statements. | |
1921 | +** | |
1922 | +** Applications that need to process SQL from untrusted sources | |
1923 | +** might also consider lowering resource limits using [sqlite3_limit()] | |
1924 | +** and limiting database size using the [max_page_count] [PRAGMA] | |
1925 | +** in addition to using an authorizer. | |
733 | 1926 | ** |
734 | 1927 | ** Only a single authorizer can be in place on a database connection |
735 | 1928 | ** at a time. Each call to sqlite3_set_authorizer overrides the |
736 | -** previous call. A NULL authorizer means that no authorization | |
737 | -** callback is invoked. The default authorizer is NULL. | |
1929 | +** previous call. Disable the authorizer by installing a NULL callback. | |
1930 | +** The authorizer is disabled by default. | |
1931 | +** | |
1932 | +** The authorizer callback must not do anything that will modify | |
1933 | +** the database connection that invoked the authorizer callback. | |
1934 | +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their | |
1935 | +** database connections for the meaning of "modify" in this paragraph. | |
738 | 1936 | ** |
739 | -** Note that the authorizer callback is invoked only during | |
1937 | +** When [sqlite3_prepare_v2()] is used to prepare a statement, the | |
1938 | +** statement might be re-prepared during [sqlite3_step()] due to a | |
1939 | +** schema change. Hence, the application should ensure that the | |
1940 | +** correct authorizer callback remains in place during the [sqlite3_step()]. | |
1941 | +** | |
1942 | +** Note that the authorizer callback is invoked only during | |
740 | 1943 | ** [sqlite3_prepare()] or its variants. Authorization is not |
741 | -** performed during statement evaluation in [sqlite3_step()]. | |
1944 | +** performed during statement evaluation in [sqlite3_step()], unless | |
1945 | +** as stated in the previous paragraph, sqlite3_step() invokes | |
1946 | +** sqlite3_prepare_v2() to reprepare a statement after a schema change. | |
1947 | +** | |
1948 | +** Requirements: | |
1949 | +** [H12501] [H12502] [H12503] [H12504] [H12505] [H12506] [H12507] [H12510] | |
1950 | +** [H12511] [H12512] [H12520] [H12521] [H12522] | |
742 | 1951 | */ |
743 | -int sqlite3_set_authorizer( | |
1952 | +SQLITE_API int sqlite3_set_authorizer( | |
744 | 1953 | sqlite3*, |
745 | 1954 | int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), |
746 | 1955 | void *pUserData |
747 | 1956 | ); |
748 | 1957 | |
749 | 1958 | /* |
750 | -** CAPI3REF: Authorizer Return Codes | |
1959 | +** CAPI3REF: Authorizer Return Codes {H12590} <H12500> | |
751 | 1960 | ** |
752 | 1961 | ** The [sqlite3_set_authorizer | authorizer callback function] must |
753 | 1962 | ** return either [SQLITE_OK] or one of these two constants in order |
@@ -759,23 +1968,26 @@ int sqlite3_set_authorizer( | ||
759 | 1968 | #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ |
760 | 1969 | |
761 | 1970 | /* |
762 | -** CAPI3REF: Authorizer Action Codes | |
1971 | +** CAPI3REF: Authorizer Action Codes {H12550} <H12500> | |
763 | 1972 | ** |
764 | 1973 | ** The [sqlite3_set_authorizer()] interface registers a callback function |
765 | -** that is invoked to authorizer certain SQL statement actions. The | |
1974 | +** that is invoked to authorize certain SQL statement actions. The | |
766 | 1975 | ** second parameter to the callback is an integer code that specifies |
767 | 1976 | ** what action is being authorized. These are the integer action codes that |
768 | 1977 | ** the authorizer callback may be passed. |
769 | 1978 | ** |
770 | -** These action code values signify what kind of operation is to be | |
771 | -** authorized. The 3rd and 4th parameters to the authorization callback | |
772 | -** function will be parameters or NULL depending on which of these | |
1979 | +** These action code values signify what kind of operation is to be | |
1980 | +** authorized. The 3rd and 4th parameters to the authorization | |
1981 | +** callback function will be parameters or NULL depending on which of these | |
773 | 1982 | ** codes is used as the second parameter. The 5th parameter to the |
774 | -** authorizer callback is the name of the database ("main", "temp", | |
1983 | +** authorizer callback is the name of the database ("main", "temp", | |
775 | 1984 | ** etc.) if applicable. The 6th parameter to the authorizer callback |
776 | 1985 | ** is the name of the inner-most trigger or view that is responsible for |
777 | -** the access attempt or NULL if this access attempt is directly from | |
1986 | +** the access attempt or NULL if this access attempt is directly from | |
778 | 1987 | ** top-level SQL code. |
1988 | +** | |
1989 | +** Requirements: | |
1990 | +** [H12551] [H12552] [H12553] [H12554] | |
779 | 1991 | */ |
780 | 1992 | /******************************************* 3rd ************ 4th ***********/ |
781 | 1993 | #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ |
@@ -799,7 +2011,7 @@ int sqlite3_set_authorizer( | ||
799 | 2011 | #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ |
800 | 2012 | #define SQLITE_READ 20 /* Table Name Column Name */ |
801 | 2013 | #define SQLITE_SELECT 21 /* NULL NULL */ |
802 | -#define SQLITE_TRANSACTION 22 /* NULL NULL */ | |
2014 | +#define SQLITE_TRANSACTION 22 /* Operation NULL */ | |
803 | 2015 | #define SQLITE_UPDATE 23 /* Table Name Column Name */ |
804 | 2016 | #define SQLITE_ATTACH 24 /* Filename NULL */ |
805 | 2017 | #define SQLITE_DETACH 25 /* Database Name NULL */ |
@@ -808,139 +2020,223 @@ int sqlite3_set_authorizer( | ||
808 | 2020 | #define SQLITE_ANALYZE 28 /* Table Name NULL */ |
809 | 2021 | #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ |
810 | 2022 | #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ |
811 | -#define SQLITE_FUNCTION 31 /* Function Name NULL */ | |
2023 | +#define SQLITE_FUNCTION 31 /* NULL Function Name */ | |
2024 | +#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */ | |
812 | 2025 | #define SQLITE_COPY 0 /* No longer used */ |
813 | 2026 | |
814 | 2027 | /* |
815 | -** CAPI3REF: Tracing And Profiling Functions | |
2028 | +** CAPI3REF: Tracing And Profiling Functions {H12280} <S60400> | |
2029 | +** EXPERIMENTAL | |
816 | 2030 | ** |
817 | 2031 | ** These routines register callback functions that can be used for |
818 | 2032 | ** tracing and profiling the execution of SQL statements. |
819 | -** The callback function registered by sqlite3_trace() is invoked | |
820 | -** at the first [sqlite3_step()] for the evaluation of an SQL statement. | |
2033 | +** | |
2034 | +** The callback function registered by sqlite3_trace() is invoked at | |
2035 | +** various times when an SQL statement is being run by [sqlite3_step()]. | |
2036 | +** The callback returns a UTF-8 rendering of the SQL statement text | |
2037 | +** as the statement first begins executing. Additional callbacks occur | |
2038 | +** as each triggered subprogram is entered. The callbacks for triggers | |
2039 | +** contain a UTF-8 SQL comment that identifies the trigger. | |
2040 | +** | |
821 | 2041 | ** The callback function registered by sqlite3_profile() is invoked |
822 | -** as each SQL statement finishes and includes | |
823 | -** information on how long that statement ran. | |
2042 | +** as each SQL statement finishes. The profile callback contains | |
2043 | +** the original statement text and an estimate of wall-clock time | |
2044 | +** of how long that statement took to run. | |
824 | 2045 | ** |
825 | -** The sqlite3_profile() API is currently considered experimental and | |
826 | -** is subject to change. | |
2046 | +** Requirements: | |
2047 | +** [H12281] [H12282] [H12283] [H12284] [H12285] [H12287] [H12288] [H12289] | |
2048 | +** [H12290] | |
827 | 2049 | */ |
828 | -void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); | |
829 | -void *sqlite3_profile(sqlite3*, | |
830 | - void(*xProfile)(void*,const char*,sqlite_uint64), void*); | |
2050 | +SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); | |
2051 | +SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*, | |
2052 | + void(*xProfile)(void*,const char*,sqlite3_uint64), void*); | |
831 | 2053 | |
832 | 2054 | /* |
833 | -** CAPI3REF: Query Progress Callbacks | |
2055 | +** CAPI3REF: Query Progress Callbacks {H12910} <S60400> | |
834 | 2056 | ** |
835 | -** This routine configures a callback function - the progress callback - that | |
836 | -** is invoked periodically during long running calls to [sqlite3_exec()], | |
837 | -** [sqlite3_step()] and [sqlite3_get_table()]. An example use for this | |
2057 | +** This routine configures a callback function - the | |
2058 | +** progress callback - that is invoked periodically during long | |
2059 | +** running calls to [sqlite3_exec()], [sqlite3_step()] and | |
2060 | +** [sqlite3_get_table()]. An example use for this | |
838 | 2061 | ** interface is to keep a GUI updated during a large query. |
839 | 2062 | ** |
840 | -** The progress callback is invoked once for every N virtual machine opcodes, | |
841 | -** where N is the second argument to this function. The progress callback | |
842 | -** itself is identified by the third argument to this function. The fourth | |
843 | -** argument to this function is a void pointer passed to the progress callback | |
844 | -** function each time it is invoked. | |
2063 | +** If the progress callback returns non-zero, the operation is | |
2064 | +** interrupted. This feature can be used to implement a | |
2065 | +** "Cancel" button on a GUI progress dialog box. | |
845 | 2066 | ** |
846 | -** If a call to [sqlite3_exec()], [sqlite3_step()], or [sqlite3_get_table()] | |
847 | -** results in fewer than N opcodes being executed, then the progress | |
848 | -** callback is never invoked. | |
849 | -** | |
850 | -** Only a single progress callback function may be registered for each | |
851 | -** open database connection. Every call to sqlite3_progress_handler() | |
852 | -** overwrites the results of the previous call. | |
853 | -** To remove the progress callback altogether, pass NULL as the third | |
854 | -** argument to this function. | |
855 | -** | |
856 | -** If the progress callback returns a result other than 0, then the current | |
857 | -** query is immediately terminated and any database changes rolled back. | |
858 | -** The containing [sqlite3_exec()], [sqlite3_step()], or | |
859 | -** [sqlite3_get_table()] call returns SQLITE_INTERRUPT. This feature | |
860 | -** can be used, for example, to implement the "Cancel" button on a | |
861 | -** progress dialog box in a GUI. | |
862 | -*/ | |
863 | -void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); | |
864 | - | |
865 | -/* | |
866 | -** CAPI3REF: Opening A New Database Connection | |
867 | -** | |
868 | -** Open the sqlite database file "filename". The "filename" is UTF-8 | |
869 | -** encoded for sqlite3_open() and UTF-16 encoded in the native byte order | |
870 | -** for sqlite3_open16(). An [sqlite3*] handle is returned in *ppDb, even | |
871 | -** if an error occurs. If the database is opened (or created) successfully, | |
872 | -** then SQLITE_OK is returned. Otherwise an error code is returned. The | |
873 | -** sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain | |
874 | -** an English language description of the error. | |
2067 | +** The progress handler must not do anything that will modify | |
2068 | +** the database connection that invoked the progress handler. | |
2069 | +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their | |
2070 | +** database connections for the meaning of "modify" in this paragraph. | |
875 | 2071 | ** |
876 | -** If the database file does not exist, then a new database will be created | |
877 | -** as needed. The default encoding for the database will be UTF-8 if | |
878 | -** sqlite3_open() is called and UTF-16 if sqlite3_open16 is used. | |
2072 | +** Requirements: | |
2073 | +** [H12911] [H12912] [H12913] [H12914] [H12915] [H12916] [H12917] [H12918] | |
879 | 2074 | ** |
880 | -** Whether or not an error occurs when it is opened, resources associated | |
881 | -** with the [sqlite3*] handle should be released by passing it to | |
882 | -** sqlite3_close() when it is no longer required. | |
2075 | +*/ | |
2076 | +SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); | |
2077 | + | |
2078 | +/* | |
2079 | +** CAPI3REF: Opening A New Database Connection {H12700} <S40200> | |
2080 | +** | |
2081 | +** These routines open an SQLite database file whose name is given by the | |
2082 | +** filename argument. The filename argument is interpreted as UTF-8 for | |
2083 | +** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte | |
2084 | +** order for sqlite3_open16(). A [database connection] handle is usually | |
2085 | +** returned in *ppDb, even if an error occurs. The only exception is that | |
2086 | +** if SQLite is unable to allocate memory to hold the [sqlite3] object, | |
2087 | +** a NULL will be written into *ppDb instead of a pointer to the [sqlite3] | |
2088 | +** object. If the database is opened (and/or created) successfully, then | |
2089 | +** [SQLITE_OK] is returned. Otherwise an [error code] is returned. The | |
2090 | +** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain | |
2091 | +** an English language description of the error. | |
883 | 2092 | ** |
884 | -** Note to windows users: The encoding used for the filename argument | |
885 | -** of sqlite3_open() must be UTF-8, not whatever codepage is currently | |
886 | -** defined. Filenames containing international characters must be converted | |
887 | -** to UTF-8 prior to passing them into sqlite3_open(). | |
2093 | +** The default encoding for the database will be UTF-8 if | |
2094 | +** sqlite3_open() or sqlite3_open_v2() is called and | |
2095 | +** UTF-16 in the native byte order if sqlite3_open16() is used. | |
2096 | +** | |
2097 | +** Whether or not an error occurs when it is opened, resources | |
2098 | +** associated with the [database connection] handle should be released by | |
2099 | +** passing it to [sqlite3_close()] when it is no longer required. | |
2100 | +** | |
2101 | +** The sqlite3_open_v2() interface works like sqlite3_open() | |
2102 | +** except that it accepts two additional parameters for additional control | |
2103 | +** over the new database connection. The flags parameter can take one of | |
2104 | +** the following three values, optionally combined with the | |
2105 | +** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE], | |
2106 | +** and/or [SQLITE_OPEN_PRIVATECACHE] flags: | |
2107 | +** | |
2108 | +** <dl> | |
2109 | +** <dt>[SQLITE_OPEN_READONLY]</dt> | |
2110 | +** <dd>The database is opened in read-only mode. If the database does not | |
2111 | +** already exist, an error is returned.</dd> | |
2112 | +** | |
2113 | +** <dt>[SQLITE_OPEN_READWRITE]</dt> | |
2114 | +** <dd>The database is opened for reading and writing if possible, or reading | |
2115 | +** only if the file is write protected by the operating system. In either | |
2116 | +** case the database must already exist, otherwise an error is returned.</dd> | |
2117 | +** | |
2118 | +** <dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt> | |
2119 | +** <dd>The database is opened for reading and writing, and is creates it if | |
2120 | +** it does not already exist. This is the behavior that is always used for | |
2121 | +** sqlite3_open() and sqlite3_open16().</dd> | |
2122 | +** </dl> | |
2123 | +** | |
2124 | +** If the 3rd parameter to sqlite3_open_v2() is not one of the | |
2125 | +** combinations shown above or one of the combinations shown above combined | |
2126 | +** with the [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], | |
2127 | +** [SQLITE_OPEN_SHAREDCACHE] and/or [SQLITE_OPEN_SHAREDCACHE] flags, | |
2128 | +** then the behavior is undefined. | |
2129 | +** | |
2130 | +** If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection | |
2131 | +** opens in the multi-thread [threading mode] as long as the single-thread | |
2132 | +** mode has not been set at compile-time or start-time. If the | |
2133 | +** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens | |
2134 | +** in the serialized [threading mode] unless single-thread was | |
2135 | +** previously selected at compile-time or start-time. | |
2136 | +** The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be | |
2137 | +** eligible to use [shared cache mode], regardless of whether or not shared | |
2138 | +** cache is enabled using [sqlite3_enable_shared_cache()]. The | |
2139 | +** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not | |
2140 | +** participate in [shared cache mode] even if it is enabled. | |
2141 | +** | |
2142 | +** If the filename is ":memory:", then a private, temporary in-memory database | |
2143 | +** is created for the connection. This in-memory database will vanish when | |
2144 | +** the database connection is closed. Future versions of SQLite might | |
2145 | +** make use of additional special filenames that begin with the ":" character. | |
2146 | +** It is recommended that when a database filename actually does begin with | |
2147 | +** a ":" character you should prefix the filename with a pathname such as | |
2148 | +** "./" to avoid ambiguity. | |
2149 | +** | |
2150 | +** If the filename is an empty string, then a private, temporary | |
2151 | +** on-disk database will be created. This private database will be | |
2152 | +** automatically deleted as soon as the database connection is closed. | |
2153 | +** | |
2154 | +** The fourth parameter to sqlite3_open_v2() is the name of the | |
2155 | +** [sqlite3_vfs] object that defines the operating system interface that | |
2156 | +** the new database connection should use. If the fourth parameter is | |
2157 | +** a NULL pointer then the default [sqlite3_vfs] object is used. | |
2158 | +** | |
2159 | +** <b>Note to Windows users:</b> The encoding used for the filename argument | |
2160 | +** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever | |
2161 | +** codepage is currently defined. Filenames containing international | |
2162 | +** characters must be converted to UTF-8 prior to passing them into | |
2163 | +** sqlite3_open() or sqlite3_open_v2(). | |
2164 | +** | |
2165 | +** Requirements: | |
2166 | +** [H12701] [H12702] [H12703] [H12704] [H12706] [H12707] [H12709] [H12711] | |
2167 | +** [H12712] [H12713] [H12714] [H12717] [H12719] [H12721] [H12723] | |
888 | 2168 | */ |
889 | -int sqlite3_open( | |
2169 | +SQLITE_API int sqlite3_open( | |
890 | 2170 | const char *filename, /* Database filename (UTF-8) */ |
891 | 2171 | sqlite3 **ppDb /* OUT: SQLite db handle */ |
892 | 2172 | ); |
893 | -int sqlite3_open16( | |
2173 | +SQLITE_API int sqlite3_open16( | |
894 | 2174 | const void *filename, /* Database filename (UTF-16) */ |
895 | 2175 | sqlite3 **ppDb /* OUT: SQLite db handle */ |
896 | 2176 | ); |
2177 | +SQLITE_API int sqlite3_open_v2( | |
2178 | + const char *filename, /* Database filename (UTF-8) */ | |
2179 | + sqlite3 **ppDb, /* OUT: SQLite db handle */ | |
2180 | + int flags, /* Flags */ | |
2181 | + const char *zVfs /* Name of VFS module to use */ | |
2182 | +); | |
897 | 2183 | |
898 | 2184 | /* |
899 | -** CAPI3REF: Error Codes And Messages | |
900 | -** | |
901 | -** The sqlite3_errcode() interface returns the numeric | |
902 | -** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code] | |
903 | -** for the most recent failed sqlite3_* API call associated | |
904 | -** with [sqlite3] handle 'db'. If a prior API call failed but the | |
905 | -** most recent API call succeeded, the return value from sqlite3_errcode() | |
906 | -** is undefined. | |
907 | -** | |
908 | -** The sqlite3_errmsg() and sqlite3_errmsg16() return English-langauge | |
909 | -** text that describes the error, as either UTF8 or UTF16 respectively. | |
910 | -** Memory to hold the error message string is managed internally. The | |
911 | -** string may be overwritten or deallocated by subsequent calls to SQLite | |
912 | -** interface functions. | |
913 | -** | |
914 | -** Calls to many sqlite3_* functions set the error code and string returned | |
915 | -** by [sqlite3_errcode()], [sqlite3_errmsg()], and [sqlite3_errmsg16()] | |
916 | -** (overwriting the previous values). Note that calls to [sqlite3_errcode()], | |
917 | -** [sqlite3_errmsg()], and [sqlite3_errmsg16()] themselves do not affect the | |
918 | -** results of future invocations. Calls to API routines that do not return | |
919 | -** an error code (examples: [sqlite3_data_count()] or [sqlite3_mprintf()]) do | |
920 | -** not change the error code returned by this routine. | |
921 | -** | |
922 | -** Assuming no other intervening sqlite3_* API calls are made, the error | |
923 | -** code returned by this function is associated with the same error as | |
924 | -** the strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()]. | |
2185 | +** CAPI3REF: Error Codes And Messages {H12800} <S60200> | |
2186 | +** | |
2187 | +** The sqlite3_errcode() interface returns the numeric [result code] or | |
2188 | +** [extended result code] for the most recent failed sqlite3_* API call | |
2189 | +** associated with a [database connection]. If a prior API call failed | |
2190 | +** but the most recent API call succeeded, the return value from | |
2191 | +** sqlite3_errcode() is undefined. The sqlite3_extended_errcode() | |
2192 | +** interface is the same except that it always returns the | |
2193 | +** [extended result code] even when extended result codes are | |
2194 | +** disabled. | |
2195 | +** | |
2196 | +** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language | |
2197 | +** text that describes the error, as either UTF-8 or UTF-16 respectively. | |
2198 | +** Memory to hold the error message string is managed internally. | |
2199 | +** The application does not need to worry about freeing the result. | |
2200 | +** However, the error string might be overwritten or deallocated by | |
2201 | +** subsequent calls to other SQLite interface functions. | |
2202 | +** | |
2203 | +** When the serialized [threading mode] is in use, it might be the | |
2204 | +** case that a second error occurs on a separate thread in between | |
2205 | +** the time of the first error and the call to these interfaces. | |
2206 | +** When that happens, the second error will be reported since these | |
2207 | +** interfaces always report the most recent result. To avoid | |
2208 | +** this, each thread can obtain exclusive use of the [database connection] D | |
2209 | +** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning | |
2210 | +** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after | |
2211 | +** all calls to the interfaces listed here are completed. | |
2212 | +** | |
2213 | +** If an interface fails with SQLITE_MISUSE, that means the interface | |
2214 | +** was invoked incorrectly by the application. In that case, the | |
2215 | +** error code and message may or may not be set. | |
2216 | +** | |
2217 | +** Requirements: | |
2218 | +** [H12801] [H12802] [H12803] [H12807] [H12808] [H12809] | |
925 | 2219 | */ |
926 | -int sqlite3_errcode(sqlite3 *db); | |
927 | -const char *sqlite3_errmsg(sqlite3*); | |
928 | -const void *sqlite3_errmsg16(sqlite3*); | |
2220 | +SQLITE_API int sqlite3_errcode(sqlite3 *db); | |
2221 | +SQLITE_API int sqlite3_extended_errcode(sqlite3 *db); | |
2222 | +SQLITE_API const char *sqlite3_errmsg(sqlite3*); | |
2223 | +SQLITE_API const void *sqlite3_errmsg16(sqlite3*); | |
929 | 2224 | |
930 | 2225 | /* |
931 | -** CAPI3REF: SQL Statement Object | |
2226 | +** CAPI3REF: SQL Statement Object {H13000} <H13010> | |
2227 | +** KEYWORDS: {prepared statement} {prepared statements} | |
932 | 2228 | ** |
933 | -** Instance of this object represent single SQL statements. This | |
934 | -** is variously known as a "prepared statement" or a | |
2229 | +** An instance of this object represents a single SQL statement. | |
2230 | +** This object is variously known as a "prepared statement" or a | |
935 | 2231 | ** "compiled SQL statement" or simply as a "statement". |
936 | -** | |
2232 | +** | |
937 | 2233 | ** The life of a statement object goes something like this: |
938 | 2234 | ** |
939 | 2235 | ** <ol> |
940 | 2236 | ** <li> Create the object using [sqlite3_prepare_v2()] or a related |
941 | 2237 | ** function. |
942 | -** <li> Bind values to host parameters using | |
943 | -** [sqlite3_bind_blob | sqlite3_bind_* interfaces]. | |
2238 | +** <li> Bind values to [host parameters] using the sqlite3_bind_*() | |
2239 | +** interfaces. | |
944 | 2240 | ** <li> Run the SQL by calling [sqlite3_step()] one or more times. |
945 | 2241 | ** <li> Reset the statement using [sqlite3_reset()] then go back |
946 | 2242 | ** to step 2. Do this zero or more times. |
@@ -953,45 +2249,151 @@ const void *sqlite3_errmsg16(sqlite3*); | ||
953 | 2249 | typedef struct sqlite3_stmt sqlite3_stmt; |
954 | 2250 | |
955 | 2251 | /* |
956 | -** CAPI3REF: Compiling An SQL Statement | |
2252 | +** CAPI3REF: Run-time Limits {H12760} <S20600> | |
2253 | +** | |
2254 | +** This interface allows the size of various constructs to be limited | |
2255 | +** on a connection by connection basis. The first parameter is the | |
2256 | +** [database connection] whose limit is to be set or queried. The | |
2257 | +** second parameter is one of the [limit categories] that define a | |
2258 | +** class of constructs to be size limited. The third parameter is the | |
2259 | +** new limit for that construct. The function returns the old limit. | |
2260 | +** | |
2261 | +** If the new limit is a negative number, the limit is unchanged. | |
2262 | +** For the limit category of SQLITE_LIMIT_XYZ there is a | |
2263 | +** [limits | hard upper bound] | |
2264 | +** set by a compile-time C preprocessor macro named | |
2265 | +** [limits | SQLITE_MAX_XYZ]. | |
2266 | +** (The "_LIMIT_" in the name is changed to "_MAX_".) | |
2267 | +** Attempts to increase a limit above its hard upper bound are | |
2268 | +** silently truncated to the hard upper limit. | |
2269 | +** | |
2270 | +** Run time limits are intended for use in applications that manage | |
2271 | +** both their own internal database and also databases that are controlled | |
2272 | +** by untrusted external sources. An example application might be a | |
2273 | +** web browser that has its own databases for storing history and | |
2274 | +** separate databases controlled by JavaScript applications downloaded | |
2275 | +** off the Internet. The internal databases can be given the | |
2276 | +** large, default limits. Databases managed by external sources can | |
2277 | +** be given much smaller limits designed to prevent a denial of service | |
2278 | +** attack. Developers might also want to use the [sqlite3_set_authorizer()] | |
2279 | +** interface to further control untrusted SQL. The size of the database | |
2280 | +** created by an untrusted script can be contained using the | |
2281 | +** [max_page_count] [PRAGMA]. | |
2282 | +** | |
2283 | +** New run-time limit categories may be added in future releases. | |
2284 | +** | |
2285 | +** Requirements: | |
2286 | +** [H12762] [H12766] [H12769] | |
2287 | +*/ | |
2288 | +SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal); | |
2289 | + | |
2290 | +/* | |
2291 | +** CAPI3REF: Run-Time Limit Categories {H12790} <H12760> | |
2292 | +** KEYWORDS: {limit category} {limit categories} | |
957 | 2293 | ** |
958 | -** To execute an SQL query, it must first be compiled into a byte-code | |
959 | -** program using one of these routines. | |
2294 | +** These constants define various performance limits | |
2295 | +** that can be lowered at run-time using [sqlite3_limit()]. | |
2296 | +** The synopsis of the meanings of the various limits is shown below. | |
2297 | +** Additional information is available at [limits | Limits in SQLite]. | |
960 | 2298 | ** |
961 | -** The first argument "db" is an [sqlite3 | SQLite database handle] | |
962 | -** obtained from a prior call to [sqlite3_open()] or [sqlite3_open16()]. | |
963 | -** The second argument "zSql" is the statement to be compiled, encoded | |
964 | -** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() | |
965 | -** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2() | |
966 | -** use UTF-16. | |
2299 | +** <dl> | |
2300 | +** <dt>SQLITE_LIMIT_LENGTH</dt> | |
2301 | +** <dd>The maximum size of any string or BLOB or table row.<dd> | |
2302 | +** | |
2303 | +** <dt>SQLITE_LIMIT_SQL_LENGTH</dt> | |
2304 | +** <dd>The maximum length of an SQL statement.</dd> | |
2305 | +** | |
2306 | +** <dt>SQLITE_LIMIT_COLUMN</dt> | |
2307 | +** <dd>The maximum number of columns in a table definition or in the | |
2308 | +** result set of a [SELECT] or the maximum number of columns in an index | |
2309 | +** or in an ORDER BY or GROUP BY clause.</dd> | |
967 | 2310 | ** |
968 | -** If the nByte argument is less | |
969 | -** than zero, then zSql is read up to the first zero terminator. If | |
970 | -** nByte is non-negative, then it is the maximum number of | |
971 | -** bytes read from zSql. When nByte is non-negative, the | |
972 | -** zSql string ends at either the first '\000' character or | |
973 | -** until the nByte-th byte, whichever comes first. | |
2311 | +** <dt>SQLITE_LIMIT_EXPR_DEPTH</dt> | |
2312 | +** <dd>The maximum depth of the parse tree on any expression.</dd> | |
974 | 2313 | ** |
975 | -** *pzTail is made to point to the first byte past the end of the first | |
976 | -** SQL statement in zSql. This routine only compiles the first statement | |
977 | -** in zSql, so *pzTail is left pointing to what remains uncompiled. | |
2314 | +** <dt>SQLITE_LIMIT_COMPOUND_SELECT</dt> | |
2315 | +** <dd>The maximum number of terms in a compound SELECT statement.</dd> | |
978 | 2316 | ** |
979 | -** *ppStmt is left pointing to a compiled | |
980 | -** [sqlite3_stmt | SQL statement structure] that can be | |
981 | -** executed using [sqlite3_step()]. Or if there is an error, *ppStmt may be | |
982 | -** set to NULL. If the input text contained no SQL (if the input is and | |
983 | -** empty string or a comment) then *ppStmt is set to NULL. The calling | |
984 | -** procedure is responsible for deleting the compiled SQL statement | |
985 | -** using [sqlite3_finalize()] after it has finished with it. | |
2317 | +** <dt>SQLITE_LIMIT_VDBE_OP</dt> | |
2318 | +** <dd>The maximum number of instructions in a virtual machine program | |
2319 | +** used to implement an SQL statement.</dd> | |
2320 | +** | |
2321 | +** <dt>SQLITE_LIMIT_FUNCTION_ARG</dt> | |
2322 | +** <dd>The maximum number of arguments on a function.</dd> | |
2323 | +** | |
2324 | +** <dt>SQLITE_LIMIT_ATTACHED</dt> | |
2325 | +** <dd>The maximum number of [ATTACH | attached databases].</dd> | |
2326 | +** | |
2327 | +** <dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt> | |
2328 | +** <dd>The maximum length of the pattern argument to the [LIKE] or | |
2329 | +** [GLOB] operators.</dd> | |
2330 | +** | |
2331 | +** <dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt> | |
2332 | +** <dd>The maximum number of variables in an SQL statement that can | |
2333 | +** be bound.</dd> | |
2334 | +** | |
2335 | +** <dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt> | |
2336 | +** <dd>The maximum depth of recursion for triggers.</dd> | |
2337 | +** </dl> | |
2338 | +*/ | |
2339 | +#define SQLITE_LIMIT_LENGTH 0 | |
2340 | +#define SQLITE_LIMIT_SQL_LENGTH 1 | |
2341 | +#define SQLITE_LIMIT_COLUMN 2 | |
2342 | +#define SQLITE_LIMIT_EXPR_DEPTH 3 | |
2343 | +#define SQLITE_LIMIT_COMPOUND_SELECT 4 | |
2344 | +#define SQLITE_LIMIT_VDBE_OP 5 | |
2345 | +#define SQLITE_LIMIT_FUNCTION_ARG 6 | |
2346 | +#define SQLITE_LIMIT_ATTACHED 7 | |
2347 | +#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8 | |
2348 | +#define SQLITE_LIMIT_VARIABLE_NUMBER 9 | |
2349 | +#define SQLITE_LIMIT_TRIGGER_DEPTH 10 | |
2350 | + | |
2351 | +/* | |
2352 | +** CAPI3REF: Compiling An SQL Statement {H13010} <S10000> | |
2353 | +** KEYWORDS: {SQL statement compiler} | |
2354 | +** | |
2355 | +** To execute an SQL query, it must first be compiled into a byte-code | |
2356 | +** program using one of these routines. | |
2357 | +** | |
2358 | +** The first argument, "db", is a [database connection] obtained from a | |
2359 | +** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or | |
2360 | +** [sqlite3_open16()]. The database connection must not have been closed. | |
2361 | +** | |
2362 | +** The second argument, "zSql", is the statement to be compiled, encoded | |
2363 | +** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() | |
2364 | +** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2() | |
2365 | +** use UTF-16. | |
986 | 2366 | ** |
987 | -** On success, [SQLITE_OK] is returned. Otherwise an | |
988 | -** [SQLITE_ERROR | error code] is returned. | |
2367 | +** If the nByte argument is less than zero, then zSql is read up to the | |
2368 | +** first zero terminator. If nByte is non-negative, then it is the maximum | |
2369 | +** number of bytes read from zSql. When nByte is non-negative, the | |
2370 | +** zSql string ends at either the first '\000' or '\u0000' character or | |
2371 | +** the nByte-th byte, whichever comes first. If the caller knows | |
2372 | +** that the supplied string is nul-terminated, then there is a small | |
2373 | +** performance advantage to be gained by passing an nByte parameter that | |
2374 | +** is equal to the number of bytes in the input string <i>including</i> | |
2375 | +** the nul-terminator bytes. | |
2376 | +** | |
2377 | +** If pzTail is not NULL then *pzTail is made to point to the first byte | |
2378 | +** past the end of the first SQL statement in zSql. These routines only | |
2379 | +** compile the first statement in zSql, so *pzTail is left pointing to | |
2380 | +** what remains uncompiled. | |
2381 | +** | |
2382 | +** *ppStmt is left pointing to a compiled [prepared statement] that can be | |
2383 | +** executed using [sqlite3_step()]. If there is an error, *ppStmt is set | |
2384 | +** to NULL. If the input text contains no SQL (if the input is an empty | |
2385 | +** string or a comment) then *ppStmt is set to NULL. | |
2386 | +** The calling procedure is responsible for deleting the compiled | |
2387 | +** SQL statement using [sqlite3_finalize()] after it has finished with it. | |
2388 | +** ppStmt may not be NULL. | |
2389 | +** | |
2390 | +** On success, [SQLITE_OK] is returned, otherwise an [error code] is returned. | |
989 | 2391 | ** |
990 | 2392 | ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are |
991 | 2393 | ** recommended for all new programs. The two older interfaces are retained |
992 | 2394 | ** for backwards compatibility, but their use is discouraged. |
993 | 2395 | ** In the "v2" interfaces, the prepared statement |
994 | -** that is returned (the [sqlite3_stmt] object) contains a copy of the | |
2396 | +** that is returned (the [sqlite3_stmt] object) contains a copy of the | |
995 | 2397 | ** original SQL text. This causes the [sqlite3_step()] interface to |
996 | 2398 | ** behave a differently in two ways: |
997 | 2399 | ** |
@@ -999,49 +2401,50 @@ typedef struct sqlite3_stmt sqlite3_stmt; | ||
999 | 2401 | ** <li> |
1000 | 2402 | ** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it |
1001 | 2403 | ** always used to do, [sqlite3_step()] will automatically recompile the SQL |
1002 | -** statement and try to run it again. If the schema has changed in a way | |
1003 | -** that makes the statement no longer valid, [sqlite3_step()] will still | |
2404 | +** statement and try to run it again. If the schema has changed in | |
2405 | +** a way that makes the statement no longer valid, [sqlite3_step()] will still | |
1004 | 2406 | ** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is |
1005 | 2407 | ** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the |
1006 | -** error go away. Note: use [sqlite3_errmsg()] to find the text of the parsing | |
1007 | -** error that results in an [SQLITE_SCHEMA] return. | |
2408 | +** error go away. Note: use [sqlite3_errmsg()] to find the text | |
2409 | +** of the parsing error that results in an [SQLITE_SCHEMA] return. | |
1008 | 2410 | ** </li> |
1009 | 2411 | ** |
1010 | 2412 | ** <li> |
1011 | -** When an error occurs, | |
1012 | -** [sqlite3_step()] will return one of the detailed | |
1013 | -** [SQLITE_ERROR | result codes] or | |
1014 | -** [SQLITE_IOERR_READ | extended result codes] such as directly. | |
1015 | -** The legacy behavior was that [sqlite3_step()] would only return a generic | |
1016 | -** [SQLITE_ERROR] result code and you would have to make a second call to | |
1017 | -** [sqlite3_reset()] in order to find the underlying cause of the problem. | |
1018 | -** With the "v2" prepare interfaces, the underlying reason for the error is | |
1019 | -** returned immediately. | |
2413 | +** When an error occurs, [sqlite3_step()] will return one of the detailed | |
2414 | +** [error codes] or [extended error codes]. The legacy behavior was that | |
2415 | +** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code | |
2416 | +** and you would have to make a second call to [sqlite3_reset()] in order | |
2417 | +** to find the underlying cause of the problem. With the "v2" prepare | |
2418 | +** interfaces, the underlying reason for the error is returned immediately. | |
1020 | 2419 | ** </li> |
1021 | 2420 | ** </ol> |
2421 | +** | |
2422 | +** Requirements: | |
2423 | +** [H13011] [H13012] [H13013] [H13014] [H13015] [H13016] [H13019] [H13021] | |
2424 | +** | |
1022 | 2425 | */ |
1023 | -int sqlite3_prepare( | |
2426 | +SQLITE_API int sqlite3_prepare( | |
1024 | 2427 | sqlite3 *db, /* Database handle */ |
1025 | 2428 | const char *zSql, /* SQL statement, UTF-8 encoded */ |
1026 | 2429 | int nByte, /* Maximum length of zSql in bytes. */ |
1027 | 2430 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
1028 | 2431 | const char **pzTail /* OUT: Pointer to unused portion of zSql */ |
1029 | 2432 | ); |
1030 | -int sqlite3_prepare_v2( | |
2433 | +SQLITE_API int sqlite3_prepare_v2( | |
1031 | 2434 | sqlite3 *db, /* Database handle */ |
1032 | 2435 | const char *zSql, /* SQL statement, UTF-8 encoded */ |
1033 | 2436 | int nByte, /* Maximum length of zSql in bytes. */ |
1034 | 2437 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
1035 | 2438 | const char **pzTail /* OUT: Pointer to unused portion of zSql */ |
1036 | 2439 | ); |
1037 | -int sqlite3_prepare16( | |
2440 | +SQLITE_API int sqlite3_prepare16( | |
1038 | 2441 | sqlite3 *db, /* Database handle */ |
1039 | 2442 | const void *zSql, /* SQL statement, UTF-16 encoded */ |
1040 | 2443 | int nByte, /* Maximum length of zSql in bytes. */ |
1041 | 2444 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
1042 | 2445 | const void **pzTail /* OUT: Pointer to unused portion of zSql */ |
1043 | 2446 | ); |
1044 | -int sqlite3_prepare16_v2( | |
2447 | +SQLITE_API int sqlite3_prepare16_v2( | |
1045 | 2448 | sqlite3 *db, /* Database handle */ |
1046 | 2449 | const void *zSql, /* SQL statement, UTF-16 encoded */ |
1047 | 2450 | int nByte, /* Maximum length of zSql in bytes. */ |
@@ -1050,84 +2453,130 @@ int sqlite3_prepare16_v2( | ||
1050 | 2453 | ); |
1051 | 2454 | |
1052 | 2455 | /* |
1053 | -** CAPI3REF: Dynamically Typed Value Object | |
2456 | +** CAPI3REF: Retrieving Statement SQL {H13100} <H13000> | |
1054 | 2457 | ** |
1055 | -** SQLite uses dynamic typing for the values it stores. Values can | |
1056 | -** be integers, floating point values, strings, BLOBs, or NULL. When | |
1057 | -** passing around values internally, each value is represented as | |
1058 | -** an instance of the sqlite3_value object. | |
2458 | +** This interface can be used to retrieve a saved copy of the original | |
2459 | +** SQL text used to create a [prepared statement] if that statement was | |
2460 | +** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()]. | |
2461 | +** | |
2462 | +** Requirements: | |
2463 | +** [H13101] [H13102] [H13103] | |
2464 | +*/ | |
2465 | +SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt); | |
2466 | + | |
2467 | +/* | |
2468 | +** CAPI3REF: Dynamically Typed Value Object {H15000} <S20200> | |
2469 | +** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value} | |
2470 | +** | |
2471 | +** SQLite uses the sqlite3_value object to represent all values | |
2472 | +** that can be stored in a database table. SQLite uses dynamic typing | |
2473 | +** for the values it stores. Values stored in sqlite3_value objects | |
2474 | +** can be integers, floating point values, strings, BLOBs, or NULL. | |
2475 | +** | |
2476 | +** An sqlite3_value object may be either "protected" or "unprotected". | |
2477 | +** Some interfaces require a protected sqlite3_value. Other interfaces | |
2478 | +** will accept either a protected or an unprotected sqlite3_value. | |
2479 | +** Every interface that accepts sqlite3_value arguments specifies | |
2480 | +** whether or not it requires a protected sqlite3_value. | |
2481 | +** | |
2482 | +** The terms "protected" and "unprotected" refer to whether or not | |
2483 | +** a mutex is held. A internal mutex is held for a protected | |
2484 | +** sqlite3_value object but no mutex is held for an unprotected | |
2485 | +** sqlite3_value object. If SQLite is compiled to be single-threaded | |
2486 | +** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0) | |
2487 | +** or if SQLite is run in one of reduced mutex modes | |
2488 | +** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD] | |
2489 | +** then there is no distinction between protected and unprotected | |
2490 | +** sqlite3_value objects and they can be used interchangeably. However, | |
2491 | +** for maximum code portability it is recommended that applications | |
2492 | +** still make the distinction between between protected and unprotected | |
2493 | +** sqlite3_value objects even when not strictly required. | |
2494 | +** | |
2495 | +** The sqlite3_value objects that are passed as parameters into the | |
2496 | +** implementation of [application-defined SQL functions] are protected. | |
2497 | +** The sqlite3_value object returned by | |
2498 | +** [sqlite3_column_value()] is unprotected. | |
2499 | +** Unprotected sqlite3_value objects may only be used with | |
2500 | +** [sqlite3_result_value()] and [sqlite3_bind_value()]. | |
2501 | +** The [sqlite3_value_blob | sqlite3_value_type()] family of | |
2502 | +** interfaces require protected sqlite3_value objects. | |
1059 | 2503 | */ |
1060 | 2504 | typedef struct Mem sqlite3_value; |
1061 | 2505 | |
1062 | 2506 | /* |
1063 | -** CAPI3REF: SQL Function Context Object | |
2507 | +** CAPI3REF: SQL Function Context Object {H16001} <S20200> | |
1064 | 2508 | ** |
1065 | 2509 | ** The context in which an SQL function executes is stored in an |
1066 | -** sqlite3_context object. A pointer to such an object is the | |
1067 | -** first parameter to user-defined SQL functions. | |
2510 | +** sqlite3_context object. A pointer to an sqlite3_context object | |
2511 | +** is always first parameter to [application-defined SQL functions]. | |
2512 | +** The application-defined SQL function implementation will pass this | |
2513 | +** pointer through into calls to [sqlite3_result_int | sqlite3_result()], | |
2514 | +** [sqlite3_aggregate_context()], [sqlite3_user_data()], | |
2515 | +** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()], | |
2516 | +** and/or [sqlite3_set_auxdata()]. | |
1068 | 2517 | */ |
1069 | 2518 | typedef struct sqlite3_context sqlite3_context; |
1070 | 2519 | |
1071 | 2520 | /* |
1072 | -** CAPI3REF: Binding Values To Prepared Statements | |
2521 | +** CAPI3REF: Binding Values To Prepared Statements {H13500} <S70300> | |
2522 | +** KEYWORDS: {host parameter} {host parameters} {host parameter name} | |
2523 | +** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding} | |
1073 | 2524 | ** |
1074 | 2525 | ** In the SQL strings input to [sqlite3_prepare_v2()] and its variants, |
1075 | -** one or more literals can be replace by a parameter in one of these | |
1076 | -** forms: | |
2526 | +** literals may be replaced by a [parameter] that matches one of following | |
2527 | +** templates: | |
1077 | 2528 | ** |
1078 | 2529 | ** <ul> |
1079 | 2530 | ** <li> ? |
1080 | 2531 | ** <li> ?NNN |
1081 | -** <li> :AAA | |
1082 | -** <li> @AAA | |
2532 | +** <li> :VVV | |
2533 | +** <li> @VVV | |
1083 | 2534 | ** <li> $VVV |
1084 | 2535 | ** </ul> |
1085 | 2536 | ** |
1086 | -** In the parameter forms shown above NNN is an integer literal, | |
1087 | -** AAA is an alphanumeric identifier and VVV is a variable name according | |
1088 | -** to the syntax rules of the TCL programming language. | |
1089 | -** The values of these parameters (also called "host parameter names") | |
2537 | +** In the templates above, NNN represents an integer literal, | |
2538 | +** and VVV represents an alphanumeric identifer. The values of these | |
2539 | +** parameters (also called "host parameter names" or "SQL parameters") | |
1090 | 2540 | ** can be set using the sqlite3_bind_*() routines defined here. |
1091 | 2541 | ** |
1092 | -** The first argument to the sqlite3_bind_*() routines always is a pointer | |
1093 | -** to the [sqlite3_stmt] object returned from [sqlite3_prepare_v2()] or | |
1094 | -** its variants. The second | |
1095 | -** argument is the index of the parameter to be set. The first parameter has | |
1096 | -** an index of 1. When the same named parameter is used more than once, second | |
1097 | -** and subsequent | |
1098 | -** occurrences have the same index as the first occurrence. The index for | |
1099 | -** named parameters can be looked up using the | |
1100 | -** [sqlite3_bind_parameter_name()] API if desired. The index for "?NNN" | |
1101 | -** parametes is the value of NNN. | |
1102 | -** The NNN value must be between 1 and the compile-time | |
1103 | -** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999). | |
1104 | -** See <a href="limits.html">limits.html</a> for additional information. | |
2542 | +** The first argument to the sqlite3_bind_*() routines is always | |
2543 | +** a pointer to the [sqlite3_stmt] object returned from | |
2544 | +** [sqlite3_prepare_v2()] or its variants. | |
2545 | +** | |
2546 | +** The second argument is the index of the SQL parameter to be set. | |
2547 | +** The leftmost SQL parameter has an index of 1. When the same named | |
2548 | +** SQL parameter is used more than once, second and subsequent | |
2549 | +** occurrences have the same index as the first occurrence. | |
2550 | +** The index for named parameters can be looked up using the | |
2551 | +** [sqlite3_bind_parameter_index()] API if desired. The index | |
2552 | +** for "?NNN" parameters is the value of NNN. | |
2553 | +** The NNN value must be between 1 and the [sqlite3_limit()] | |
2554 | +** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999). | |
1105 | 2555 | ** |
1106 | 2556 | ** The third argument is the value to bind to the parameter. |
1107 | 2557 | ** |
1108 | -** In those | |
1109 | -** routines that have a fourth argument, its value is the number of bytes | |
1110 | -** in the parameter. To be clear: the value is the number of bytes in the | |
1111 | -** string, not the number of characters. The number | |
1112 | -** of bytes does not include the zero-terminator at the end of strings. | |
2558 | +** In those routines that have a fourth argument, its value is the | |
2559 | +** number of bytes in the parameter. To be clear: the value is the | |
2560 | +** number of <u>bytes</u> in the value, not the number of characters. | |
1113 | 2561 | ** If the fourth parameter is negative, the length of the string is |
1114 | -** number of bytes up to the first zero terminator. | |
2562 | +** the number of bytes up to the first zero terminator. | |
1115 | 2563 | ** |
1116 | 2564 | ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and |
1117 | 2565 | ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or |
1118 | -** text after SQLite has finished with it. If the fifth argument is the | |
1119 | -** special value [SQLITE_STATIC], then the library assumes that the information | |
1120 | -** is in static, unmanaged space and does not need to be freed. If the | |
1121 | -** fifth argument has the value [SQLITE_TRANSIENT], then SQLite makes its | |
1122 | -** own private copy of the data immediately, before the sqlite3_bind_*() | |
1123 | -** routine returns. | |
1124 | -** | |
1125 | -** The sqlite3_bind_zeroblob() routine binds a BLOB of length n that | |
1126 | -** is filled with zeros. A zeroblob uses a fixed amount of memory | |
1127 | -** (just an integer to hold it size) while it is being processed. | |
1128 | -** Zeroblobs are intended to serve as place-holders for BLOBs whose | |
1129 | -** content is later written using | |
1130 | -** [sqlite3_blob_open | increment BLOB I/O] routines. | |
2566 | +** string after SQLite has finished with it. If the fifth argument is | |
2567 | +** the special value [SQLITE_STATIC], then SQLite assumes that the | |
2568 | +** information is in static, unmanaged space and does not need to be freed. | |
2569 | +** If the fifth argument has the value [SQLITE_TRANSIENT], then | |
2570 | +** SQLite makes its own private copy of the data immediately, before | |
2571 | +** the sqlite3_bind_*() routine returns. | |
2572 | +** | |
2573 | +** The sqlite3_bind_zeroblob() routine binds a BLOB of length N that | |
2574 | +** is filled with zeroes. A zeroblob uses a fixed amount of memory | |
2575 | +** (just an integer to hold its size) while it is being processed. | |
2576 | +** Zeroblobs are intended to serve as placeholders for BLOBs whose | |
2577 | +** content is later written using | |
2578 | +** [sqlite3_blob_open | incremental BLOB I/O] routines. | |
2579 | +** A negative value for the zeroblob results in a zero-length BLOB. | |
1131 | 2580 | ** |
1132 | 2581 | ** The sqlite3_bind_*() routines must be called after |
1133 | 2582 | ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and |
@@ -1137,166 +2586,231 @@ typedef struct sqlite3_context sqlite3_context; | ||
1137 | 2586 | ** |
1138 | 2587 | ** These routines return [SQLITE_OK] on success or an error code if |
1139 | 2588 | ** anything goes wrong. [SQLITE_RANGE] is returned if the parameter |
1140 | -** index is out of range. [SQLITE_NOMEM] is returned if malloc fails. | |
1141 | -** [SQLITE_MISUSE] is returned if these routines are called on a virtual | |
1142 | -** machine that is the wrong state or which has already been finalized. | |
1143 | -*/ | |
1144 | -int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); | |
1145 | -int sqlite3_bind_double(sqlite3_stmt*, int, double); | |
1146 | -int sqlite3_bind_int(sqlite3_stmt*, int, int); | |
1147 | -int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite_int64); | |
1148 | -int sqlite3_bind_null(sqlite3_stmt*, int); | |
1149 | -int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); | |
1150 | -int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); | |
1151 | -int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); | |
1152 | -int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); | |
1153 | - | |
1154 | -/* | |
1155 | -** CAPI3REF: Number Of Host Parameters | |
1156 | -** | |
1157 | -** Return the largest host parameter index in the precompiled statement given | |
1158 | -** as the argument. When the host parameters are of the forms like ":AAA" | |
1159 | -** or "?", then they are assigned sequential increasing numbers beginning | |
1160 | -** with one, so the value returned is the number of parameters. However | |
1161 | -** if the same host parameter name is used multiple times, each occurrance | |
1162 | -** is given the same number, so the value returned in that case is the number | |
1163 | -** of unique host parameter names. If host parameters of the form "?NNN" | |
1164 | -** are used (where NNN is an integer) then there might be gaps in the | |
1165 | -** numbering and the value returned by this interface is the index of the | |
1166 | -** host parameter with the largest index value. | |
1167 | -*/ | |
1168 | -int sqlite3_bind_parameter_count(sqlite3_stmt*); | |
1169 | - | |
1170 | -/* | |
1171 | -** CAPI3REF: Name Of A Host Parameter | |
1172 | -** | |
1173 | -** This routine returns a pointer to the name of the n-th parameter in a | |
1174 | -** [sqlite3_stmt | prepared statement]. | |
1175 | -** Host parameters of the form ":AAA" or "@AAA" or "$VVV" have a name | |
1176 | -** which is the string ":AAA" or "@AAA" or "$VVV". | |
1177 | -** In other words, the initial ":" or "$" or "@" | |
2589 | +** index is out of range. [SQLITE_NOMEM] is returned if malloc() fails. | |
2590 | +** [SQLITE_MISUSE] might be returned if these routines are called on a | |
2591 | +** virtual machine that is the wrong state or which has already been finalized. | |
2592 | +** Detection of misuse is unreliable. Applications should not depend | |
2593 | +** on SQLITE_MISUSE returns. SQLITE_MISUSE is intended to indicate a | |
2594 | +** a logic error in the application. Future versions of SQLite might | |
2595 | +** panic rather than return SQLITE_MISUSE. | |
2596 | +** | |
2597 | +** See also: [sqlite3_bind_parameter_count()], | |
2598 | +** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()]. | |
2599 | +** | |
2600 | +** Requirements: | |
2601 | +** [H13506] [H13509] [H13512] [H13515] [H13518] [H13521] [H13524] [H13527] | |
2602 | +** [H13530] [H13533] [H13536] [H13539] [H13542] [H13545] [H13548] [H13551] | |
2603 | +** | |
2604 | +*/ | |
2605 | +SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); | |
2606 | +SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double); | |
2607 | +SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int); | |
2608 | +SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); | |
2609 | +SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int); | |
2610 | +SQLITE_API int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); | |
2611 | +SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); | |
2612 | +SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); | |
2613 | +SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); | |
2614 | + | |
2615 | +/* | |
2616 | +** CAPI3REF: Number Of SQL Parameters {H13600} <S70300> | |
2617 | +** | |
2618 | +** This routine can be used to find the number of [SQL parameters] | |
2619 | +** in a [prepared statement]. SQL parameters are tokens of the | |
2620 | +** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as | |
2621 | +** placeholders for values that are [sqlite3_bind_blob | bound] | |
2622 | +** to the parameters at a later time. | |
2623 | +** | |
2624 | +** This routine actually returns the index of the largest (rightmost) | |
2625 | +** parameter. For all forms except ?NNN, this will correspond to the | |
2626 | +** number of unique parameters. If parameters of the ?NNN are used, | |
2627 | +** there may be gaps in the list. | |
2628 | +** | |
2629 | +** See also: [sqlite3_bind_blob|sqlite3_bind()], | |
2630 | +** [sqlite3_bind_parameter_name()], and | |
2631 | +** [sqlite3_bind_parameter_index()]. | |
2632 | +** | |
2633 | +** Requirements: | |
2634 | +** [H13601] | |
2635 | +*/ | |
2636 | +SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*); | |
2637 | + | |
2638 | +/* | |
2639 | +** CAPI3REF: Name Of A Host Parameter {H13620} <S70300> | |
2640 | +** | |
2641 | +** This routine returns a pointer to the name of the n-th | |
2642 | +** [SQL parameter] in a [prepared statement]. | |
2643 | +** SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA" | |
2644 | +** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA" | |
2645 | +** respectively. | |
2646 | +** In other words, the initial ":" or "$" or "@" or "?" | |
1178 | 2647 | ** is included as part of the name. |
1179 | -** Parameters of the form "?" or "?NNN" have no name. | |
2648 | +** Parameters of the form "?" without a following integer have no name | |
2649 | +** and are also referred to as "anonymous parameters". | |
2650 | +** | |
2651 | +** The first host parameter has an index of 1, not 0. | |
1180 | 2652 | ** |
1181 | -** The first bound parameter has an index of 1, not 0. | |
2653 | +** If the value n is out of range or if the n-th parameter is | |
2654 | +** nameless, then NULL is returned. The returned string is | |
2655 | +** always in UTF-8 encoding even if the named parameter was | |
2656 | +** originally specified as UTF-16 in [sqlite3_prepare16()] or | |
2657 | +** [sqlite3_prepare16_v2()]. | |
1182 | 2658 | ** |
1183 | -** If the value n is out of range or if the n-th parameter is nameless, | |
1184 | -** then NULL is returned. The returned string is always in the | |
1185 | -** UTF-8 encoding even if the named parameter was originally specified | |
1186 | -** as UTF-16 in [sqlite3_prepare16()] or [sqlite3_prepare16_v2()]. | |
2659 | +** See also: [sqlite3_bind_blob|sqlite3_bind()], | |
2660 | +** [sqlite3_bind_parameter_count()], and | |
2661 | +** [sqlite3_bind_parameter_index()]. | |
2662 | +** | |
2663 | +** Requirements: | |
2664 | +** [H13621] | |
1187 | 2665 | */ |
1188 | -const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); | |
2666 | +SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); | |
1189 | 2667 | |
1190 | 2668 | /* |
1191 | -** CAPI3REF: Index Of A Parameter With A Given Name | |
2669 | +** CAPI3REF: Index Of A Parameter With A Given Name {H13640} <S70300> | |
2670 | +** | |
2671 | +** Return the index of an SQL parameter given its name. The | |
2672 | +** index value returned is suitable for use as the second | |
2673 | +** parameter to [sqlite3_bind_blob|sqlite3_bind()]. A zero | |
2674 | +** is returned if no matching parameter is found. The parameter | |
2675 | +** name must be given in UTF-8 even if the original statement | |
2676 | +** was prepared from UTF-16 text using [sqlite3_prepare16_v2()]. | |
1192 | 2677 | ** |
1193 | -** This routine returns the index of a host parameter with the given name. | |
1194 | -** The name must match exactly. If no parameter with the given name is | |
1195 | -** found, return 0. Parameter names must be UTF8. | |
2678 | +** See also: [sqlite3_bind_blob|sqlite3_bind()], | |
2679 | +** [sqlite3_bind_parameter_count()], and | |
2680 | +** [sqlite3_bind_parameter_index()]. | |
2681 | +** | |
2682 | +** Requirements: | |
2683 | +** [H13641] | |
1196 | 2684 | */ |
1197 | -int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); | |
2685 | +SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); | |
1198 | 2686 | |
1199 | 2687 | /* |
1200 | -** CAPI3REF: Reset All Bindings On A Prepared Statement | |
2688 | +** CAPI3REF: Reset All Bindings On A Prepared Statement {H13660} <S70300> | |
2689 | +** | |
2690 | +** Contrary to the intuition of many, [sqlite3_reset()] does not reset | |
2691 | +** the [sqlite3_bind_blob | bindings] on a [prepared statement]. | |
2692 | +** Use this routine to reset all host parameters to NULL. | |
1201 | 2693 | ** |
1202 | -** Contrary to the intuition of many, [sqlite3_reset()] does not | |
1203 | -** reset the [sqlite3_bind_blob | bindings] on a | |
1204 | -** [sqlite3_stmt | prepared statement]. Use this routine to | |
1205 | -** reset all host parameters to NULL. | |
2694 | +** Requirements: | |
2695 | +** [H13661] | |
1206 | 2696 | */ |
1207 | -int sqlite3_clear_bindings(sqlite3_stmt*); | |
2697 | +SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*); | |
1208 | 2698 | |
1209 | 2699 | /* |
1210 | -** CAPI3REF: Number Of Columns In A Result Set | |
2700 | +** CAPI3REF: Number Of Columns In A Result Set {H13710} <S10700> | |
1211 | 2701 | ** |
1212 | -** Return the number of columns in the result set returned by the | |
1213 | -** [sqlite3_stmt | compiled SQL statement]. This routine returns 0 | |
1214 | -** if pStmt is an SQL statement that does not return data (for | |
1215 | -** example an UPDATE). | |
2702 | +** Return the number of columns in the result set returned by the | |
2703 | +** [prepared statement]. This routine returns 0 if pStmt is an SQL | |
2704 | +** statement that does not return data (for example an [UPDATE]). | |
2705 | +** | |
2706 | +** Requirements: | |
2707 | +** [H13711] | |
1216 | 2708 | */ |
1217 | -int sqlite3_column_count(sqlite3_stmt *pStmt); | |
2709 | +SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt); | |
1218 | 2710 | |
1219 | 2711 | /* |
1220 | -** CAPI3REF: Column Names In A Result Set | |
2712 | +** CAPI3REF: Column Names In A Result Set {H13720} <S10700> | |
1221 | 2713 | ** |
1222 | 2714 | ** These routines return the name assigned to a particular column |
1223 | -** in the result set of a SELECT statement. The sqlite3_column_name() | |
1224 | -** interface returns a pointer to a UTF8 string and sqlite3_column_name16() | |
1225 | -** returns a pointer to a UTF16 string. The first parameter is the | |
1226 | -** [sqlite_stmt | prepared statement] that implements the SELECT statement. | |
1227 | -** The second parameter is the column number. The left-most column is | |
1228 | -** number 0. | |
1229 | -** | |
1230 | -** The returned string pointer is valid until either the | |
1231 | -** [sqlite_stmt | prepared statement] is destroyed by [sqlite3_finalize()] | |
1232 | -** or until the next call sqlite3_column_name() or sqlite3_column_name16() | |
1233 | -** on the same column. | |
2715 | +** in the result set of a [SELECT] statement. The sqlite3_column_name() | |
2716 | +** interface returns a pointer to a zero-terminated UTF-8 string | |
2717 | +** and sqlite3_column_name16() returns a pointer to a zero-terminated | |
2718 | +** UTF-16 string. The first parameter is the [prepared statement] | |
2719 | +** that implements the [SELECT] statement. The second parameter is the | |
2720 | +** column number. The leftmost column is number 0. | |
2721 | +** | |
2722 | +** The returned string pointer is valid until either the [prepared statement] | |
2723 | +** is destroyed by [sqlite3_finalize()] or until the next call to | |
2724 | +** sqlite3_column_name() or sqlite3_column_name16() on the same column. | |
2725 | +** | |
2726 | +** If sqlite3_malloc() fails during the processing of either routine | |
2727 | +** (for example during a conversion from UTF-8 to UTF-16) then a | |
2728 | +** NULL pointer is returned. | |
2729 | +** | |
2730 | +** The name of a result column is the value of the "AS" clause for | |
2731 | +** that column, if there is an AS clause. If there is no AS clause | |
2732 | +** then the name of the column is unspecified and may change from | |
2733 | +** one release of SQLite to the next. | |
2734 | +** | |
2735 | +** Requirements: | |
2736 | +** [H13721] [H13723] [H13724] [H13725] [H13726] [H13727] | |
1234 | 2737 | */ |
1235 | -const char *sqlite3_column_name(sqlite3_stmt*, int N); | |
1236 | -const void *sqlite3_column_name16(sqlite3_stmt*, int N); | |
2738 | +SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N); | |
2739 | +SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N); | |
1237 | 2740 | |
1238 | 2741 | /* |
1239 | -** CAPI3REF: Source Of Data In A Query Result | |
2742 | +** CAPI3REF: Source Of Data In A Query Result {H13740} <S10700> | |
1240 | 2743 | ** |
1241 | 2744 | ** These routines provide a means to determine what column of what |
1242 | -** table in which database a result of a SELECT statement comes from. | |
2745 | +** table in which database a result of a [SELECT] statement comes from. | |
1243 | 2746 | ** The name of the database or table or column can be returned as |
1244 | -** either a UTF8 or UTF16 string. The _database_ routines return | |
2747 | +** either a UTF-8 or UTF-16 string. The _database_ routines return | |
1245 | 2748 | ** the database name, the _table_ routines return the table name, and |
1246 | 2749 | ** the origin_ routines return the column name. |
1247 | -** The returned string is valid until | |
1248 | -** the [sqlite3_stmt | prepared statement] is destroyed using | |
1249 | -** [sqlite3_finalize()] or until the same information is requested | |
2750 | +** The returned string is valid until the [prepared statement] is destroyed | |
2751 | +** using [sqlite3_finalize()] or until the same information is requested | |
1250 | 2752 | ** again in a different encoding. |
1251 | 2753 | ** |
1252 | 2754 | ** The names returned are the original un-aliased names of the |
1253 | 2755 | ** database, table, and column. |
1254 | 2756 | ** |
1255 | -** The first argument to the following calls is a | |
1256 | -** [sqlite3_stmt | compiled SQL statement]. | |
1257 | -** These functions return information about the Nth column returned by | |
2757 | +** The first argument to the following calls is a [prepared statement]. | |
2758 | +** These functions return information about the Nth column returned by | |
1258 | 2759 | ** the statement, where N is the second function argument. |
1259 | 2760 | ** |
1260 | -** If the Nth column returned by the statement is an expression | |
1261 | -** or subquery and is not a column value, then all of these functions | |
1262 | -** return NULL. Otherwise, they return the | |
1263 | -** name of the attached database, table and column that query result | |
1264 | -** column was extracted from. | |
2761 | +** If the Nth column returned by the statement is an expression or | |
2762 | +** subquery and is not a column value, then all of these functions return | |
2763 | +** NULL. These routine might also return NULL if a memory allocation error | |
2764 | +** occurs. Otherwise, they return the name of the attached database, table | |
2765 | +** and column that query result column was extracted from. | |
2766 | +** | |
2767 | +** As with all other SQLite APIs, those postfixed with "16" return | |
2768 | +** UTF-16 encoded strings, the other functions return UTF-8. {END} | |
1265 | 2769 | ** |
1266 | -** As with all other SQLite APIs, those postfixed with "16" return UTF-16 | |
1267 | -** encoded strings, the other functions return UTF-8. | |
2770 | +** These APIs are only available if the library was compiled with the | |
2771 | +** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined. | |
1268 | 2772 | ** |
1269 | -** These APIs are only available if the library was compiled with the | |
1270 | -** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. | |
2773 | +** {A13751} | |
2774 | +** If two or more threads call one or more of these routines against the same | |
2775 | +** prepared statement and column at the same time then the results are | |
2776 | +** undefined. | |
2777 | +** | |
2778 | +** Requirements: | |
2779 | +** [H13741] [H13742] [H13743] [H13744] [H13745] [H13746] [H13748] | |
2780 | +** | |
2781 | +** If two or more threads call one or more | |
2782 | +** [sqlite3_column_database_name | column metadata interfaces] | |
2783 | +** for the same [prepared statement] and result column | |
2784 | +** at the same time then the results are undefined. | |
1271 | 2785 | */ |
1272 | -const char *sqlite3_column_database_name(sqlite3_stmt*,int); | |
1273 | -const void *sqlite3_column_database_name16(sqlite3_stmt*,int); | |
1274 | -const char *sqlite3_column_table_name(sqlite3_stmt*,int); | |
1275 | -const void *sqlite3_column_table_name16(sqlite3_stmt*,int); | |
1276 | -const char *sqlite3_column_origin_name(sqlite3_stmt*,int); | |
1277 | -const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); | |
2786 | +SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int); | |
2787 | +SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int); | |
2788 | +SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int); | |
2789 | +SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int); | |
2790 | +SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int); | |
2791 | +SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); | |
1278 | 2792 | |
1279 | 2793 | /* |
1280 | -** CAPI3REF: Declared Datatype Of A Query Result | |
2794 | +** CAPI3REF: Declared Datatype Of A Query Result {H13760} <S10700> | |
1281 | 2795 | ** |
1282 | -** The first parameter is a [sqlite3_stmt | compiled SQL statement]. | |
1283 | -** If this statement is a SELECT statement and the Nth column of the | |
1284 | -** returned result set of that SELECT is a table column (not an | |
2796 | +** The first parameter is a [prepared statement]. | |
2797 | +** If this statement is a [SELECT] statement and the Nth column of the | |
2798 | +** returned result set of that [SELECT] is a table column (not an | |
1285 | 2799 | ** expression or subquery) then the declared type of the table |
1286 | -** column is returned. If the Nth column of the result set is an | |
2800 | +** column is returned. If the Nth column of the result set is an | |
1287 | 2801 | ** expression or subquery, then a NULL pointer is returned. |
1288 | -** The returned string is always UTF-8 encoded. For example, in | |
1289 | -** the database schema: | |
2802 | +** The returned string is always UTF-8 encoded. {END} | |
2803 | +** | |
2804 | +** For example, given the database schema: | |
1290 | 2805 | ** |
1291 | 2806 | ** CREATE TABLE t1(c1 VARIANT); |
1292 | 2807 | ** |
1293 | -** And the following statement compiled: | |
2808 | +** and the following statement to be compiled: | |
1294 | 2809 | ** |
1295 | 2810 | ** SELECT c1 + 1, c1 FROM t1; |
1296 | 2811 | ** |
1297 | -** Then this routine would return the string "VARIANT" for the second | |
1298 | -** result column (i==1), and a NULL pointer for the first result column | |
1299 | -** (i==0). | |
2812 | +** this routine would return the string "VARIANT" for the second result | |
2813 | +** column (i==1), and a NULL pointer for the first result column (i==0). | |
1300 | 2814 | ** |
1301 | 2815 | ** SQLite uses dynamic run-time typing. So just because a column |
1302 | 2816 | ** is declared to contain a particular type does not mean that the |
@@ -1304,36 +2818,37 @@ const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); | ||
1304 | 2818 | ** strongly typed, but the typing is dynamic not static. Type |
1305 | 2819 | ** is associated with individual values, not with the containers |
1306 | 2820 | ** used to hold those values. |
2821 | +** | |
2822 | +** Requirements: | |
2823 | +** [H13761] [H13762] [H13763] | |
1307 | 2824 | */ |
1308 | -const char *sqlite3_column_decltype(sqlite3_stmt *, int i); | |
1309 | -const void *sqlite3_column_decltype16(sqlite3_stmt*,int); | |
2825 | +SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int); | |
2826 | +SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int); | |
1310 | 2827 | |
1311 | -/* | |
1312 | -** CAPI3REF: Evaluate An SQL Statement | |
2828 | +/* | |
2829 | +** CAPI3REF: Evaluate An SQL Statement {H13200} <S10000> | |
1313 | 2830 | ** |
1314 | -** After an [sqlite3_stmt | SQL statement] has been prepared with a call | |
1315 | -** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of | |
1316 | -** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], | |
1317 | -** then this function must be called one or more times to evaluate the | |
1318 | -** statement. | |
2831 | +** After a [prepared statement] has been prepared using either | |
2832 | +** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy | |
2833 | +** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function | |
2834 | +** must be called one or more times to evaluate the statement. | |
1319 | 2835 | ** |
1320 | -** The details of the behavior of this sqlite3_step() interface depend | |
2836 | +** The details of the behavior of the sqlite3_step() interface depend | |
1321 | 2837 | ** on whether the statement was prepared using the newer "v2" interface |
1322 | 2838 | ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy |
1323 | 2839 | ** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the |
1324 | 2840 | ** new "v2" interface is recommended for new applications but the legacy |
1325 | 2841 | ** interface will continue to be supported. |
1326 | 2842 | ** |
1327 | -** In the lagacy interface, the return value will be either [SQLITE_BUSY], | |
2843 | +** In the legacy interface, the return value will be either [SQLITE_BUSY], | |
1328 | 2844 | ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE]. |
1329 | -** With the "v2" interface, any of the other [SQLITE_OK | result code] | |
1330 | -** or [SQLITE_IOERR_READ | extended result code] might be returned as | |
1331 | -** well. | |
2845 | +** With the "v2" interface, any of the other [result codes] or | |
2846 | +** [extended result codes] might be returned as well. | |
1332 | 2847 | ** |
1333 | 2848 | ** [SQLITE_BUSY] means that the database engine was unable to acquire the |
1334 | -** database locks it needs to do its job. If the statement is a COMMIT | |
2849 | +** database locks it needs to do its job. If the statement is a [COMMIT] | |
1335 | 2850 | ** or occurs outside of an explicit transaction, then you can retry the |
1336 | -** statement. If the statement is not a COMMIT and occurs within a | |
2851 | +** statement. If the statement is not a [COMMIT] and occurs within a | |
1337 | 2852 | ** explicit transaction then you should rollback the transaction before |
1338 | 2853 | ** continuing. |
1339 | 2854 | ** |
@@ -1342,62 +2857,59 @@ const void *sqlite3_column_decltype16(sqlite3_stmt*,int); | ||
1342 | 2857 | ** machine without first calling [sqlite3_reset()] to reset the virtual |
1343 | 2858 | ** machine back to its initial state. |
1344 | 2859 | ** |
1345 | -** If the SQL statement being executed returns any data, then | |
1346 | -** [SQLITE_ROW] is returned each time a new row of data is ready | |
1347 | -** for processing by the caller. The values may be accessed using | |
1348 | -** the [sqlite3_column_int | column access functions]. | |
2860 | +** If the SQL statement being executed returns any data, then [SQLITE_ROW] | |
2861 | +** is returned each time a new row of data is ready for processing by the | |
2862 | +** caller. The values may be accessed using the [column access functions]. | |
1349 | 2863 | ** sqlite3_step() is called again to retrieve the next row of data. |
1350 | -** | |
2864 | +** | |
1351 | 2865 | ** [SQLITE_ERROR] means that a run-time error (such as a constraint |
1352 | 2866 | ** violation) has occurred. sqlite3_step() should not be called again on |
1353 | 2867 | ** the VM. More information may be found by calling [sqlite3_errmsg()]. |
1354 | -** With the legacy interface, a more specific error code (example: | |
2868 | +** With the legacy interface, a more specific error code (for example, | |
1355 | 2869 | ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth) |
1356 | 2870 | ** can be obtained by calling [sqlite3_reset()] on the |
1357 | -** [sqlite_stmt | prepared statement]. In the "v2" interface, | |
2871 | +** [prepared statement]. In the "v2" interface, | |
1358 | 2872 | ** the more specific error code is returned directly by sqlite3_step(). |
1359 | 2873 | ** |
1360 | 2874 | ** [SQLITE_MISUSE] means that the this routine was called inappropriately. |
1361 | -** Perhaps it was called on a [sqlite_stmt | prepared statement] that has | |
1362 | -** already been [sqlite3_finalize | finalized] or on one that had | |
2875 | +** Perhaps it was called on a [prepared statement] that has | |
2876 | +** already been [sqlite3_finalize | finalized] or on one that had | |
1363 | 2877 | ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could |
1364 | 2878 | ** be the case that the same database connection is being used by two or |
1365 | 2879 | ** more threads at the same moment in time. |
1366 | 2880 | ** |
1367 | -** <b>Goofy Interface Alert:</b> | |
1368 | -** In the legacy interface, | |
1369 | -** the sqlite3_step() API always returns a generic error code, | |
1370 | -** [SQLITE_ERROR], following any error other than [SQLITE_BUSY] | |
1371 | -** and [SQLITE_MISUSE]. You must call [sqlite3_reset()] or | |
1372 | -** [sqlite3_finalize()] in order to find one of the specific | |
1373 | -** [SQLITE_ERROR | result codes] that better describes the error. | |
2881 | +** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step() | |
2882 | +** API always returns a generic error code, [SQLITE_ERROR], following any | |
2883 | +** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call | |
2884 | +** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the | |
2885 | +** specific [error codes] that better describes the error. | |
1374 | 2886 | ** We admit that this is a goofy design. The problem has been fixed |
1375 | 2887 | ** with the "v2" interface. If you prepare all of your SQL statements |
1376 | 2888 | ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead |
1377 | -** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the | |
1378 | -** more specific [SQLITE_ERROR | result codes] are returned directly | |
2889 | +** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces, | |
2890 | +** then the more specific [error codes] are returned directly | |
1379 | 2891 | ** by sqlite3_step(). The use of the "v2" interface is recommended. |
2892 | +** | |
2893 | +** Requirements: | |
2894 | +** [H13202] [H15304] [H15306] [H15308] [H15310] | |
1380 | 2895 | */ |
1381 | -int sqlite3_step(sqlite3_stmt*); | |
2896 | +SQLITE_API int sqlite3_step(sqlite3_stmt*); | |
1382 | 2897 | |
1383 | 2898 | /* |
1384 | -** CAPI3REF: | |
2899 | +** CAPI3REF: Number of columns in a result set {H13770} <S10700> | |
1385 | 2900 | ** |
1386 | -** Return the number of values in the current row of the result set. | |
2901 | +** Returns the number of values in the current row of the result set. | |
1387 | 2902 | ** |
1388 | -** After a call to [sqlite3_step()] that returns [SQLITE_ROW], this routine | |
1389 | -** will return the same value as the [sqlite3_column_count()] function. | |
1390 | -** After [sqlite3_step()] has returned an [SQLITE_DONE], [SQLITE_BUSY], or | |
1391 | -** a [SQLITE_ERROR | error code], or before [sqlite3_step()] has been | |
1392 | -** called on the [sqlite_stmt | prepared statement] for the first time, | |
1393 | -** this routine returns zero. | |
2903 | +** Requirements: | |
2904 | +** [H13771] [H13772] | |
1394 | 2905 | */ |
1395 | -int sqlite3_data_count(sqlite3_stmt *pStmt); | |
2906 | +SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt); | |
1396 | 2907 | |
1397 | 2908 | /* |
1398 | -** CAPI3REF: Fundamental Datatypes | |
2909 | +** CAPI3REF: Fundamental Datatypes {H10265} <S10110><S10120> | |
2910 | +** KEYWORDS: SQLITE_TEXT | |
1399 | 2911 | ** |
1400 | -** Every value in SQLite has one of five fundamental datatypes: | |
2912 | +** {H10266} Every value in SQLite has one of five fundamental datatypes: | |
1401 | 2913 | ** |
1402 | 2914 | ** <ul> |
1403 | 2915 | ** <li> 64-bit signed integer |
@@ -1405,13 +2917,13 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); | ||
1405 | 2917 | ** <li> string |
1406 | 2918 | ** <li> BLOB |
1407 | 2919 | ** <li> NULL |
1408 | -** </ul> | |
2920 | +** </ul> {END} | |
1409 | 2921 | ** |
1410 | 2922 | ** These constants are codes for each of those types. |
1411 | 2923 | ** |
1412 | 2924 | ** Note that the SQLITE_TEXT constant was also used in SQLite version 2 |
1413 | 2925 | ** for a completely different meaning. Software that links against both |
1414 | -** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not | |
2926 | +** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not | |
1415 | 2927 | ** SQLITE_TEXT. |
1416 | 2928 | */ |
1417 | 2929 | #define SQLITE_INTEGER 1 |
@@ -1426,21 +2938,31 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); | ||
1426 | 2938 | #define SQLITE3_TEXT 3 |
1427 | 2939 | |
1428 | 2940 | /* |
1429 | -** CAPI3REF: Results Values From A Query | |
1430 | -** | |
1431 | -** These routines return information about the information | |
1432 | -** in a single column of the current result row of a query. In every | |
1433 | -** case the first argument is a pointer to the | |
1434 | -** [sqlite3_stmt | SQL statement] that is being | |
1435 | -** evaluate (the [sqlite_stmt*] that was returned from | |
1436 | -** [sqlite3_prepare_v2()] or one of its variants) and | |
1437 | -** the second argument is the index of the column for which information | |
1438 | -** should be returned. The left-most column has an index of 0. | |
1439 | -** | |
1440 | -** If the SQL statement is not currently point to a valid row, or if the | |
1441 | -** the column index is out of range, the result is undefined. | |
1442 | -** | |
1443 | -** The sqlite3_column_type() routine returns | |
2941 | +** CAPI3REF: Result Values From A Query {H13800} <S10700> | |
2942 | +** KEYWORDS: {column access functions} | |
2943 | +** | |
2944 | +** These routines form the "result set query" interface. | |
2945 | +** | |
2946 | +** These routines return information about a single column of the current | |
2947 | +** result row of a query. In every case the first argument is a pointer | |
2948 | +** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*] | |
2949 | +** that was returned from [sqlite3_prepare_v2()] or one of its variants) | |
2950 | +** and the second argument is the index of the column for which information | |
2951 | +** should be returned. The leftmost column of the result set has the index 0. | |
2952 | +** | |
2953 | +** If the SQL statement does not currently point to a valid row, or if the | |
2954 | +** column index is out of range, the result is undefined. | |
2955 | +** These routines may only be called when the most recent call to | |
2956 | +** [sqlite3_step()] has returned [SQLITE_ROW] and neither | |
2957 | +** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently. | |
2958 | +** If any of these routines are called after [sqlite3_reset()] or | |
2959 | +** [sqlite3_finalize()] or after [sqlite3_step()] has returned | |
2960 | +** something other than [SQLITE_ROW], the results are undefined. | |
2961 | +** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()] | |
2962 | +** are called from a different thread while any of these routines | |
2963 | +** are pending, then the results are undefined. | |
2964 | +** | |
2965 | +** The sqlite3_column_type() routine returns the | |
1444 | 2966 | ** [SQLITE_INTEGER | datatype code] for the initial data type |
1445 | 2967 | ** of the result column. The returned value is one of [SQLITE_INTEGER], |
1446 | 2968 | ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value |
@@ -1450,7 +2972,7 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); | ||
1450 | 2972 | ** versions of SQLite may change the behavior of sqlite3_column_type() |
1451 | 2973 | ** following a type conversion. |
1452 | 2974 | ** |
1453 | -** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() | |
2975 | +** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() | |
1454 | 2976 | ** routine returns the number of bytes in that BLOB or string. |
1455 | 2977 | ** If the result is a UTF-16 string, then sqlite3_column_bytes() converts |
1456 | 2978 | ** the string to UTF-8 and then returns the number of bytes. |
@@ -1461,20 +2983,32 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); | ||
1461 | 2983 | ** of the string. For clarity: the value returned is the number of |
1462 | 2984 | ** bytes in the string, not the number of characters. |
1463 | 2985 | ** |
2986 | +** Strings returned by sqlite3_column_text() and sqlite3_column_text16(), | |
2987 | +** even empty strings, are always zero terminated. The return | |
2988 | +** value from sqlite3_column_blob() for a zero-length BLOB is an arbitrary | |
2989 | +** pointer, possibly even a NULL pointer. | |
2990 | +** | |
1464 | 2991 | ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes() |
1465 | -** but leaves the result in UTF-16 instead of UTF-8. | |
2992 | +** but leaves the result in UTF-16 in native byte order instead of UTF-8. | |
1466 | 2993 | ** The zero terminator is not included in this count. |
1467 | 2994 | ** |
2995 | +** The object returned by [sqlite3_column_value()] is an | |
2996 | +** [unprotected sqlite3_value] object. An unprotected sqlite3_value object | |
2997 | +** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()]. | |
2998 | +** If the [unprotected sqlite3_value] object returned by | |
2999 | +** [sqlite3_column_value()] is used in any other way, including calls | |
3000 | +** to routines like [sqlite3_value_int()], [sqlite3_value_text()], | |
3001 | +** or [sqlite3_value_bytes()], then the behavior is undefined. | |
3002 | +** | |
1468 | 3003 | ** These routines attempt to convert the value where appropriate. For |
1469 | 3004 | ** example, if the internal representation is FLOAT and a text result |
1470 | -** is requested, [sqlite3_snprintf()] is used internally to do the conversion | |
1471 | -** automatically. The following table details the conversions that | |
1472 | -** are applied: | |
3005 | +** is requested, [sqlite3_snprintf()] is used internally to perform the | |
3006 | +** conversion automatically. The following table details the conversions | |
3007 | +** that are applied: | |
1473 | 3008 | ** |
1474 | 3009 | ** <blockquote> |
1475 | 3010 | ** <table border="1"> |
1476 | -** <tr><th> Internal <th> Requested <th> | |
1477 | -** <tr><th> Type <th> Type <th> Conversion | |
3011 | +** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion | |
1478 | 3012 | ** |
1479 | 3013 | ** <tr><td> NULL <td> INTEGER <td> Result is 0 |
1480 | 3014 | ** <tr><td> NULL <td> FLOAT <td> Result is 0.0 |
@@ -1482,7 +3016,7 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); | ||
1482 | 3016 | ** <tr><td> NULL <td> BLOB <td> Result is NULL pointer |
1483 | 3017 | ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float |
1484 | 3018 | ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer |
1485 | -** <tr><td> INTEGER <td> BLOB <td> Same as for INTEGER->TEXT | |
3019 | +** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT | |
1486 | 3020 | ** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer |
1487 | 3021 | ** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float |
1488 | 3022 | ** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT |
@@ -1497,176 +3031,233 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); | ||
1497 | 3031 | ** |
1498 | 3032 | ** The table above makes reference to standard C library functions atoi() |
1499 | 3033 | ** and atof(). SQLite does not really use these functions. It has its |
1500 | -** on equavalent internal routines. The atoi() and atof() names are | |
3034 | +** own equivalent internal routines. The atoi() and atof() names are | |
1501 | 3035 | ** used in the table for brevity and because they are familiar to most |
1502 | 3036 | ** C programmers. |
1503 | 3037 | ** |
1504 | 3038 | ** Note that when type conversions occur, pointers returned by prior |
1505 | 3039 | ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or |
1506 | -** sqlite3_column_text16() may be invalidated. | |
3040 | +** sqlite3_column_text16() may be invalidated. | |
1507 | 3041 | ** Type conversions and pointer invalidations might occur |
1508 | 3042 | ** in the following cases: |
1509 | 3043 | ** |
1510 | 3044 | ** <ul> |
1511 | -** <li><p> The initial content is a BLOB and sqlite3_column_text() | |
1512 | -** or sqlite3_column_text16() is called. A zero-terminator might | |
1513 | -** need to be added to the string.</p></li> | |
1514 | -** | |
1515 | -** <li><p> The initial content is UTF-8 text and sqlite3_column_bytes16() or | |
1516 | -** sqlite3_column_text16() is called. The content must be converted | |
1517 | -** to UTF-16.</p></li> | |
1518 | -** | |
1519 | -** <li><p> The initial content is UTF-16 text and sqlite3_column_bytes() or | |
1520 | -** sqlite3_column_text() is called. The content must be converted | |
1521 | -** to UTF-8.</p></li> | |
3045 | +** <li> The initial content is a BLOB and sqlite3_column_text() or | |
3046 | +** sqlite3_column_text16() is called. A zero-terminator might | |
3047 | +** need to be added to the string.</li> | |
3048 | +** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or | |
3049 | +** sqlite3_column_text16() is called. The content must be converted | |
3050 | +** to UTF-16.</li> | |
3051 | +** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or | |
3052 | +** sqlite3_column_text() is called. The content must be converted | |
3053 | +** to UTF-8.</li> | |
1522 | 3054 | ** </ul> |
1523 | 3055 | ** |
1524 | 3056 | ** Conversions between UTF-16be and UTF-16le are always done in place and do |
1525 | 3057 | ** not invalidate a prior pointer, though of course the content of the buffer |
1526 | 3058 | ** that the prior pointer points to will have been modified. Other kinds |
1527 | -** of conversion are done in place when it is possible, but sometime it is | |
1528 | -** not possible and in those cases prior pointers are invalidated. | |
3059 | +** of conversion are done in place when it is possible, but sometimes they | |
3060 | +** are not possible and in those cases prior pointers are invalidated. | |
1529 | 3061 | ** |
1530 | 3062 | ** The safest and easiest to remember policy is to invoke these routines |
1531 | 3063 | ** in one of the following ways: |
1532 | 3064 | ** |
1533 | -** <ul> | |
3065 | +** <ul> | |
1534 | 3066 | ** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li> |
1535 | 3067 | ** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li> |
1536 | 3068 | ** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li> |
1537 | -** </ul> | |
1538 | -** | |
1539 | -** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(), | |
1540 | -** or sqlite3_column_text16() first to force the result into the desired | |
1541 | -** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to | |
1542 | -** find the size of the result. Do not mix call to sqlite3_column_text() or | |
1543 | -** sqlite3_column_blob() with calls to sqlite3_column_bytes16(). And do not | |
1544 | -** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes(). | |
1545 | -*/ | |
1546 | -const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); | |
1547 | -int sqlite3_column_bytes(sqlite3_stmt*, int iCol); | |
1548 | -int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); | |
1549 | -double sqlite3_column_double(sqlite3_stmt*, int iCol); | |
1550 | -int sqlite3_column_int(sqlite3_stmt*, int iCol); | |
1551 | -sqlite_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); | |
1552 | -const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); | |
1553 | -const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); | |
1554 | -int sqlite3_column_type(sqlite3_stmt*, int iCol); | |
1555 | -sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); | |
1556 | - | |
1557 | -/* | |
1558 | -** CAPI3REF: Destroy A Prepared Statement Object | |
1559 | -** | |
1560 | -** The sqlite3_finalize() function is called to delete a | |
1561 | -** [sqlite3_stmt | compiled SQL statement]. If the statement was | |
1562 | -** executed successfully, or not executed at all, then SQLITE_OK is returned. | |
1563 | -** If execution of the statement failed then an | |
1564 | -** [SQLITE_ERROR | error code] or [SQLITE_IOERR_READ | extended error code] | |
1565 | -** is returned. | |
3069 | +** </ul> | |
3070 | +** | |
3071 | +** In other words, you should call sqlite3_column_text(), | |
3072 | +** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result | |
3073 | +** into the desired format, then invoke sqlite3_column_bytes() or | |
3074 | +** sqlite3_column_bytes16() to find the size of the result. Do not mix calls | |
3075 | +** to sqlite3_column_text() or sqlite3_column_blob() with calls to | |
3076 | +** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() | |
3077 | +** with calls to sqlite3_column_bytes(). | |
3078 | +** | |
3079 | +** The pointers returned are valid until a type conversion occurs as | |
3080 | +** described above, or until [sqlite3_step()] or [sqlite3_reset()] or | |
3081 | +** [sqlite3_finalize()] is called. The memory space used to hold strings | |
3082 | +** and BLOBs is freed automatically. Do <b>not</b> pass the pointers returned | |
3083 | +** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into | |
3084 | +** [sqlite3_free()]. | |
3085 | +** | |
3086 | +** If a memory allocation error occurs during the evaluation of any | |
3087 | +** of these routines, a default value is returned. The default value | |
3088 | +** is either the integer 0, the floating point number 0.0, or a NULL | |
3089 | +** pointer. Subsequent calls to [sqlite3_errcode()] will return | |
3090 | +** [SQLITE_NOMEM]. | |
3091 | +** | |
3092 | +** Requirements: | |
3093 | +** [H13803] [H13806] [H13809] [H13812] [H13815] [H13818] [H13821] [H13824] | |
3094 | +** [H13827] [H13830] | |
3095 | +*/ | |
3096 | +SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); | |
3097 | +SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol); | |
3098 | +SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); | |
3099 | +SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol); | |
3100 | +SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol); | |
3101 | +SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); | |
3102 | +SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); | |
3103 | +SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); | |
3104 | +SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol); | |
3105 | +SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); | |
3106 | + | |
3107 | +/* | |
3108 | +** CAPI3REF: Destroy A Prepared Statement Object {H13300} <S70300><S30100> | |
3109 | +** | |
3110 | +** The sqlite3_finalize() function is called to delete a [prepared statement]. | |
3111 | +** If the statement was executed successfully or not executed at all, then | |
3112 | +** SQLITE_OK is returned. If execution of the statement failed then an | |
3113 | +** [error code] or [extended error code] is returned. | |
1566 | 3114 | ** |
1567 | 3115 | ** This routine can be called at any point during the execution of the |
1568 | -** [sqlite3_stmt | virtual machine]. If the virtual machine has not | |
3116 | +** [prepared statement]. If the virtual machine has not | |
1569 | 3117 | ** completed execution when this routine is called, that is like |
1570 | -** encountering an error or an interrupt. (See [sqlite3_interrupt()].) | |
1571 | -** Incomplete updates may be rolled back and transactions cancelled, | |
1572 | -** depending on the circumstances, and the | |
1573 | -** [SQLITE_ERROR | result code] returned will be [SQLITE_ABORT]. | |
3118 | +** encountering an error or an [sqlite3_interrupt | interrupt]. | |
3119 | +** Incomplete updates may be rolled back and transactions canceled, | |
3120 | +** depending on the circumstances, and the | |
3121 | +** [error code] returned will be [SQLITE_ABORT]. | |
3122 | +** | |
3123 | +** Requirements: | |
3124 | +** [H11302] [H11304] | |
1574 | 3125 | */ |
1575 | -int sqlite3_finalize(sqlite3_stmt *pStmt); | |
3126 | +SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt); | |
1576 | 3127 | |
1577 | 3128 | /* |
1578 | -** CAPI3REF: Reset A Prepared Statement Object | |
3129 | +** CAPI3REF: Reset A Prepared Statement Object {H13330} <S70300> | |
1579 | 3130 | ** |
1580 | -** The sqlite3_reset() function is called to reset a | |
1581 | -** [sqlite_stmt | compiled SQL statement] object. | |
1582 | -** back to it's initial state, ready to be re-executed. | |
3131 | +** The sqlite3_reset() function is called to reset a [prepared statement] | |
3132 | +** object back to its initial state, ready to be re-executed. | |
1583 | 3133 | ** Any SQL statement variables that had values bound to them using |
1584 | 3134 | ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values. |
1585 | 3135 | ** Use [sqlite3_clear_bindings()] to reset the bindings. |
1586 | -*/ | |
1587 | -int sqlite3_reset(sqlite3_stmt *pStmt); | |
1588 | - | |
1589 | -/* | |
1590 | -** CAPI3REF: Create Or Redefine SQL Functions | |
1591 | 3136 | ** |
1592 | -** The following two functions are used to add SQL functions or aggregates | |
1593 | -** or to redefine the behavior of existing SQL functions or aggregates. The | |
1594 | -** difference only between the two is that the second parameter, the | |
1595 | -** name of the (scalar) function or aggregate, is encoded in UTF-8 for | |
1596 | -** sqlite3_create_function() and UTF-16 for sqlite3_create_function16(). | |
3137 | +** {H11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S | |
3138 | +** back to the beginning of its program. | |
3139 | +** | |
3140 | +** {H11334} If the most recent call to [sqlite3_step(S)] for the | |
3141 | +** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE], | |
3142 | +** or if [sqlite3_step(S)] has never before been called on S, | |
3143 | +** then [sqlite3_reset(S)] returns [SQLITE_OK]. | |
1597 | 3144 | ** |
1598 | -** The first argument is the [sqlite3 | database handle] that holds the | |
1599 | -** SQL function or aggregate is to be added or redefined. If a single | |
1600 | -** program uses more than one database handle internally, then SQL | |
1601 | -** functions or aggregates must be added individually to each database | |
1602 | -** handle with which they will be used. | |
3145 | +** {H11336} If the most recent call to [sqlite3_step(S)] for the | |
3146 | +** [prepared statement] S indicated an error, then | |
3147 | +** [sqlite3_reset(S)] returns an appropriate [error code]. | |
1603 | 3148 | ** |
1604 | -** The second parameter is the name of the SQL function to be created | |
1605 | -** or redefined. | |
1606 | -** The length of the name is limited to 255 bytes, exclusive of the | |
1607 | -** zero-terminator. Note that the name length limit is in bytes, not | |
3149 | +** {H11338} The [sqlite3_reset(S)] interface does not change the values | |
3150 | +** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S. | |
3151 | +*/ | |
3152 | +SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt); | |
3153 | + | |
3154 | +/* | |
3155 | +** CAPI3REF: Create Or Redefine SQL Functions {H16100} <S20200> | |
3156 | +** KEYWORDS: {function creation routines} | |
3157 | +** KEYWORDS: {application-defined SQL function} | |
3158 | +** KEYWORDS: {application-defined SQL functions} | |
3159 | +** | |
3160 | +** These two functions (collectively known as "function creation routines") | |
3161 | +** are used to add SQL functions or aggregates or to redefine the behavior | |
3162 | +** of existing SQL functions or aggregates. The only difference between the | |
3163 | +** two is that the second parameter, the name of the (scalar) function or | |
3164 | +** aggregate, is encoded in UTF-8 for sqlite3_create_function() and UTF-16 | |
3165 | +** for sqlite3_create_function16(). | |
3166 | +** | |
3167 | +** The first parameter is the [database connection] to which the SQL | |
3168 | +** function is to be added. If a single program uses more than one database | |
3169 | +** connection internally, then SQL functions must be added individually to | |
3170 | +** each database connection. | |
3171 | +** | |
3172 | +** The second parameter is the name of the SQL function to be created or | |
3173 | +** redefined. The length of the name is limited to 255 bytes, exclusive of | |
3174 | +** the zero-terminator. Note that the name length limit is in bytes, not | |
1608 | 3175 | ** characters. Any attempt to create a function with a longer name |
1609 | -** will result in an SQLITE_ERROR error. | |
3176 | +** will result in [SQLITE_ERROR] being returned. | |
1610 | 3177 | ** |
1611 | -** The third parameter is the number of arguments that the SQL function or | |
1612 | -** aggregate takes. If this parameter is negative, then the SQL function or | |
1613 | -** aggregate may take any number of arguments. | |
3178 | +** The third parameter (nArg) | |
3179 | +** is the number of arguments that the SQL function or | |
3180 | +** aggregate takes. If this parameter is -1, then the SQL function or | |
3181 | +** aggregate may take any number of arguments between 0 and the limit | |
3182 | +** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]). If the third | |
3183 | +** parameter is less than -1 or greater than 127 then the behavior is | |
3184 | +** undefined. | |
1614 | 3185 | ** |
1615 | -** The fourth parameter, eTextRep, specifies what | |
3186 | +** The fourth parameter, eTextRep, specifies what | |
1616 | 3187 | ** [SQLITE_UTF8 | text encoding] this SQL function prefers for |
1617 | 3188 | ** its parameters. Any SQL function implementation should be able to work |
1618 | 3189 | ** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be |
1619 | -** more efficient with one encoding than another. It is allowed to | |
1620 | -** invoke sqlite_create_function() or sqlite3_create_function16() multiple | |
3190 | +** more efficient with one encoding than another. An application may | |
3191 | +** invoke sqlite3_create_function() or sqlite3_create_function16() multiple | |
1621 | 3192 | ** times with the same function but with different values of eTextRep. |
1622 | 3193 | ** When multiple implementations of the same function are available, SQLite |
1623 | 3194 | ** will pick the one that involves the least amount of data conversion. |
1624 | -** If there is only a single implementation which does not care what | |
1625 | -** text encoding is used, then the fourth argument should be | |
1626 | -** [SQLITE_ANY]. | |
3195 | +** If there is only a single implementation which does not care what text | |
3196 | +** encoding is used, then the fourth argument should be [SQLITE_ANY]. | |
1627 | 3197 | ** |
1628 | -** The fifth parameter is an arbitrary pointer. The implementation | |
1629 | -** of the function can gain access to this pointer using | |
1630 | -** [sqlite_user_data()]. | |
3198 | +** The fifth parameter is an arbitrary pointer. The implementation of the | |
3199 | +** function can gain access to this pointer using [sqlite3_user_data()]. | |
1631 | 3200 | ** |
1632 | 3201 | ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are |
1633 | -** pointers to C-language functions that implement the SQL | |
1634 | -** function or aggregate. A scalar SQL function requires an implementation of | |
1635 | -** the xFunc callback only, NULL pointers should be passed as the xStep | |
1636 | -** and xFinal parameters. An aggregate SQL function requires an implementation | |
1637 | -** of xStep and xFinal and NULL should be passed for xFunc. To delete an | |
1638 | -** existing SQL function or aggregate, pass NULL for all three function | |
1639 | -** callback. | |
3202 | +** pointers to C-language functions that implement the SQL function or | |
3203 | +** aggregate. A scalar SQL function requires an implementation of the xFunc | |
3204 | +** callback only, NULL pointers should be passed as the xStep and xFinal | |
3205 | +** parameters. An aggregate SQL function requires an implementation of xStep | |
3206 | +** and xFinal and NULL should be passed for xFunc. To delete an existing | |
3207 | +** SQL function or aggregate, pass NULL for all three function callbacks. | |
1640 | 3208 | ** |
1641 | 3209 | ** It is permitted to register multiple implementations of the same |
1642 | 3210 | ** functions with the same name but with either differing numbers of |
1643 | -** arguments or differing perferred text encodings. SQLite will use | |
1644 | -** the implementation most closely matches the way in which the | |
1645 | -** SQL function is used. | |
3211 | +** arguments or differing preferred text encodings. SQLite will use | |
3212 | +** the implementation that most closely matches the way in which the | |
3213 | +** SQL function is used. A function implementation with a non-negative | |
3214 | +** nArg parameter is a better match than a function implementation with | |
3215 | +** a negative nArg. A function where the preferred text encoding | |
3216 | +** matches the database encoding is a better | |
3217 | +** match than a function where the encoding is different. | |
3218 | +** A function where the encoding difference is between UTF16le and UTF16be | |
3219 | +** is a closer match than a function where the encoding difference is | |
3220 | +** between UTF8 and UTF16. | |
3221 | +** | |
3222 | +** Built-in functions may be overloaded by new application-defined functions. | |
3223 | +** The first application-defined function with a given name overrides all | |
3224 | +** built-in functions in the same [database connection] with the same name. | |
3225 | +** Subsequent application-defined functions of the same name only override | |
3226 | +** prior application-defined functions that are an exact match for the | |
3227 | +** number of parameters and preferred encoding. | |
3228 | +** | |
3229 | +** An application-defined function is permitted to call other | |
3230 | +** SQLite interfaces. However, such calls must not | |
3231 | +** close the database connection nor finalize or reset the prepared | |
3232 | +** statement in which the function is running. | |
3233 | +** | |
3234 | +** Requirements: | |
3235 | +** [H16103] [H16106] [H16109] [H16112] [H16118] [H16121] [H16127] | |
3236 | +** [H16130] [H16133] [H16136] [H16139] [H16142] | |
1646 | 3237 | */ |
1647 | -int sqlite3_create_function( | |
1648 | - sqlite3 *, | |
3238 | +SQLITE_API int sqlite3_create_function( | |
3239 | + sqlite3 *db, | |
1649 | 3240 | const char *zFunctionName, |
1650 | 3241 | int nArg, |
1651 | 3242 | int eTextRep, |
1652 | - void*, | |
3243 | + void *pApp, | |
1653 | 3244 | void (*xFunc)(sqlite3_context*,int,sqlite3_value**), |
1654 | 3245 | void (*xStep)(sqlite3_context*,int,sqlite3_value**), |
1655 | 3246 | void (*xFinal)(sqlite3_context*) |
1656 | 3247 | ); |
1657 | -int sqlite3_create_function16( | |
1658 | - sqlite3*, | |
3248 | +SQLITE_API int sqlite3_create_function16( | |
3249 | + sqlite3 *db, | |
1659 | 3250 | const void *zFunctionName, |
1660 | 3251 | int nArg, |
1661 | 3252 | int eTextRep, |
1662 | - void*, | |
3253 | + void *pApp, | |
1663 | 3254 | void (*xFunc)(sqlite3_context*,int,sqlite3_value**), |
1664 | 3255 | void (*xStep)(sqlite3_context*,int,sqlite3_value**), |
1665 | 3256 | void (*xFinal)(sqlite3_context*) |
1666 | 3257 | ); |
1667 | 3258 | |
1668 | 3259 | /* |
1669 | -** CAPI3REF: Text Encodings | |
3260 | +** CAPI3REF: Text Encodings {H10267} <S50200> <H16100> | |
1670 | 3261 | ** |
1671 | 3262 | ** These constant define integer codes that represent the various |
1672 | 3263 | ** text encodings supported by SQLite. |
@@ -1679,22 +3270,26 @@ int sqlite3_create_function16( | ||
1679 | 3270 | #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ |
1680 | 3271 | |
1681 | 3272 | /* |
1682 | -** CAPI3REF: Obsolete Functions | |
3273 | +** CAPI3REF: Deprecated Functions | |
3274 | +** DEPRECATED | |
1683 | 3275 | ** |
1684 | -** These functions are all now obsolete. In order to maintain | |
1685 | -** backwards compatibility with older code, we continue to support | |
1686 | -** these functions. However, new development projects should avoid | |
3276 | +** These functions are [deprecated]. In order to maintain | |
3277 | +** backwards compatibility with older code, these functions continue | |
3278 | +** to be supported. However, new applications should avoid | |
1687 | 3279 | ** the use of these functions. To help encourage people to avoid |
1688 | -** using these functions, we are not going to tell you want they do. | |
3280 | +** using these functions, we are not going to tell you what they do. | |
1689 | 3281 | */ |
1690 | -int sqlite3_aggregate_count(sqlite3_context*); | |
1691 | -int sqlite3_expired(sqlite3_stmt*); | |
1692 | -int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); | |
1693 | -int sqlite3_global_recover(void); | |
1694 | - | |
3282 | +#ifndef SQLITE_OMIT_DEPRECATED | |
3283 | +SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*); | |
3284 | +SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*); | |
3285 | +SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); | |
3286 | +SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void); | |
3287 | +SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void); | |
3288 | +SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64); | |
3289 | +#endif | |
1695 | 3290 | |
1696 | 3291 | /* |
1697 | -** CAPI3REF: Obtaining SQL Function Parameter Values | |
3292 | +** CAPI3REF: Obtaining SQL Function Parameter Values {H15100} <S20200> | |
1698 | 3293 | ** |
1699 | 3294 | ** The C-language implementation of SQL functions and aggregates uses |
1700 | 3295 | ** this set of interface routines to access the parameter values on |
@@ -1704,118 +3299,172 @@ int sqlite3_global_recover(void); | ||
1704 | 3299 | ** to [sqlite3_create_function()] and [sqlite3_create_function16()] |
1705 | 3300 | ** define callbacks that implement the SQL functions and aggregates. |
1706 | 3301 | ** The 4th parameter to these callbacks is an array of pointers to |
1707 | -** [sqlite3_value] objects. There is one [sqlite3_value] object for | |
3302 | +** [protected sqlite3_value] objects. There is one [sqlite3_value] object for | |
1708 | 3303 | ** each parameter to the SQL function. These routines are used to |
1709 | 3304 | ** extract values from the [sqlite3_value] objects. |
1710 | 3305 | ** |
1711 | -** These routines work just like the corresponding | |
1712 | -** [sqlite3_column_blob | sqlite3_column_* routines] except that | |
1713 | -** these routines take a single [sqlite3_value*] pointer instead | |
1714 | -** of an [sqlite3_stmt*] pointer and an integer column number. | |
3306 | +** These routines work only with [protected sqlite3_value] objects. | |
3307 | +** Any attempt to use these routines on an [unprotected sqlite3_value] | |
3308 | +** object results in undefined behavior. | |
3309 | +** | |
3310 | +** These routines work just like the corresponding [column access functions] | |
3311 | +** except that these routines take a single [protected sqlite3_value] object | |
3312 | +** pointer instead of a [sqlite3_stmt*] pointer and an integer column number. | |
1715 | 3313 | ** |
1716 | -** The sqlite3_value_text16() interface extracts a UTF16 string | |
3314 | +** The sqlite3_value_text16() interface extracts a UTF-16 string | |
1717 | 3315 | ** in the native byte-order of the host machine. The |
1718 | 3316 | ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces |
1719 | -** extract UTF16 strings as big-endian and little-endian respectively. | |
3317 | +** extract UTF-16 strings as big-endian and little-endian respectively. | |
1720 | 3318 | ** |
1721 | 3319 | ** The sqlite3_value_numeric_type() interface attempts to apply |
1722 | 3320 | ** numeric affinity to the value. This means that an attempt is |
1723 | 3321 | ** made to convert the value to an integer or floating point. If |
1724 | -** such a conversion is possible without loss of information (in order | |
1725 | -** words if the value is original a string that looks like a number) | |
1726 | -** then it is done. Otherwise no conversion occurs. The | |
1727 | -** [SQLITE_INTEGER | datatype] after conversion is returned. | |
3322 | +** such a conversion is possible without loss of information (in other | |
3323 | +** words, if the value is a string that looks like a number) | |
3324 | +** then the conversion is performed. Otherwise no conversion occurs. | |
3325 | +** The [SQLITE_INTEGER | datatype] after conversion is returned. | |
1728 | 3326 | ** |
1729 | -** Please pay particular attention to the fact that the pointer that | |
1730 | -** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or | |
3327 | +** Please pay particular attention to the fact that the pointer returned | |
3328 | +** from [sqlite3_value_blob()], [sqlite3_value_text()], or | |
1731 | 3329 | ** [sqlite3_value_text16()] can be invalidated by a subsequent call to |
1732 | -** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite_value_text()], | |
1733 | -** or [sqlite3_value_text16()]. | |
3330 | +** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], | |
3331 | +** or [sqlite3_value_text16()]. | |
3332 | +** | |
3333 | +** These routines must be called from the same thread as | |
3334 | +** the SQL function that supplied the [sqlite3_value*] parameters. | |
3335 | +** | |
3336 | +** Requirements: | |
3337 | +** [H15103] [H15106] [H15109] [H15112] [H15115] [H15118] [H15121] [H15124] | |
3338 | +** [H15127] [H15130] [H15133] [H15136] | |
1734 | 3339 | */ |
1735 | -const void *sqlite3_value_blob(sqlite3_value*); | |
1736 | -int sqlite3_value_bytes(sqlite3_value*); | |
1737 | -int sqlite3_value_bytes16(sqlite3_value*); | |
1738 | -double sqlite3_value_double(sqlite3_value*); | |
1739 | -int sqlite3_value_int(sqlite3_value*); | |
1740 | -sqlite_int64 sqlite3_value_int64(sqlite3_value*); | |
1741 | -const unsigned char *sqlite3_value_text(sqlite3_value*); | |
1742 | -const void *sqlite3_value_text16(sqlite3_value*); | |
1743 | -const void *sqlite3_value_text16le(sqlite3_value*); | |
1744 | -const void *sqlite3_value_text16be(sqlite3_value*); | |
1745 | -int sqlite3_value_type(sqlite3_value*); | |
1746 | -int sqlite3_value_numeric_type(sqlite3_value*); | |
3340 | +SQLITE_API const void *sqlite3_value_blob(sqlite3_value*); | |
3341 | +SQLITE_API int sqlite3_value_bytes(sqlite3_value*); | |
3342 | +SQLITE_API int sqlite3_value_bytes16(sqlite3_value*); | |
3343 | +SQLITE_API double sqlite3_value_double(sqlite3_value*); | |
3344 | +SQLITE_API int sqlite3_value_int(sqlite3_value*); | |
3345 | +SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*); | |
3346 | +SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*); | |
3347 | +SQLITE_API const void *sqlite3_value_text16(sqlite3_value*); | |
3348 | +SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*); | |
3349 | +SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*); | |
3350 | +SQLITE_API int sqlite3_value_type(sqlite3_value*); | |
3351 | +SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*); | |
1747 | 3352 | |
1748 | 3353 | /* |
1749 | -** CAPI3REF: Obtain Aggregate Function Context | |
3354 | +** CAPI3REF: Obtain Aggregate Function Context {H16210} <S20200> | |
1750 | 3355 | ** |
1751 | 3356 | ** The implementation of aggregate SQL functions use this routine to allocate |
1752 | -** a structure for storing their state. The first time this routine | |
1753 | -** is called for a particular aggregate, a new structure of size nBytes | |
1754 | -** is allocated, zeroed, and returned. On subsequent calls (for the | |
1755 | -** same aggregate instance) the same buffer is returned. The implementation | |
1756 | -** of the aggregate can use the returned buffer to accumulate data. | |
3357 | +** a structure for storing their state. | |
1757 | 3358 | ** |
1758 | -** The buffer allocated is freed automatically by SQLite whan the aggregate | |
3359 | +** The first time the sqlite3_aggregate_context() routine is called for a | |
3360 | +** particular aggregate, SQLite allocates nBytes of memory, zeroes out that | |
3361 | +** memory, and returns a pointer to it. On second and subsequent calls to | |
3362 | +** sqlite3_aggregate_context() for the same aggregate function index, | |
3363 | +** the same buffer is returned. The implementation of the aggregate can use | |
3364 | +** the returned buffer to accumulate data. | |
3365 | +** | |
3366 | +** SQLite automatically frees the allocated buffer when the aggregate | |
1759 | 3367 | ** query concludes. |
1760 | 3368 | ** |
1761 | -** The first parameter should be a copy of the | |
1762 | -** [sqlite3_context | SQL function context] that is the first | |
1763 | -** parameter to the callback routine that implements the aggregate | |
1764 | -** function. | |
3369 | +** The first parameter should be a copy of the | |
3370 | +** [sqlite3_context | SQL function context] that is the first parameter | |
3371 | +** to the callback routine that implements the aggregate function. | |
3372 | +** | |
3373 | +** This routine must be called from the same thread in which | |
3374 | +** the aggregate SQL function is running. | |
3375 | +** | |
3376 | +** Requirements: | |
3377 | +** [H16211] [H16213] [H16215] [H16217] | |
1765 | 3378 | */ |
1766 | -void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); | |
3379 | +SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); | |
1767 | 3380 | |
1768 | 3381 | /* |
1769 | -** CAPI3REF: User Data For Functions | |
3382 | +** CAPI3REF: User Data For Functions {H16240} <S20200> | |
3383 | +** | |
3384 | +** The sqlite3_user_data() interface returns a copy of | |
3385 | +** the pointer that was the pUserData parameter (the 5th parameter) | |
3386 | +** of the [sqlite3_create_function()] | |
3387 | +** and [sqlite3_create_function16()] routines that originally | |
3388 | +** registered the application defined function. {END} | |
3389 | +** | |
3390 | +** This routine must be called from the same thread in which | |
3391 | +** the application-defined function is running. | |
1770 | 3392 | ** |
1771 | -** The pUserData parameter to the [sqlite3_create_function()] | |
1772 | -** and [sqlite3_create_function16()] routines | |
1773 | -** used to register user functions is available to | |
1774 | -** the implementation of the function using this call. | |
3393 | +** Requirements: | |
3394 | +** [H16243] | |
1775 | 3395 | */ |
1776 | -void *sqlite3_user_data(sqlite3_context*); | |
3396 | +SQLITE_API void *sqlite3_user_data(sqlite3_context*); | |
1777 | 3397 | |
1778 | 3398 | /* |
1779 | -** CAPI3REF: Function Auxiliary Data | |
3399 | +** CAPI3REF: Database Connection For Functions {H16250} <S60600><S20200> | |
3400 | +** | |
3401 | +** The sqlite3_context_db_handle() interface returns a copy of | |
3402 | +** the pointer to the [database connection] (the 1st parameter) | |
3403 | +** of the [sqlite3_create_function()] | |
3404 | +** and [sqlite3_create_function16()] routines that originally | |
3405 | +** registered the application defined function. | |
3406 | +** | |
3407 | +** Requirements: | |
3408 | +** [H16253] | |
3409 | +*/ | |
3410 | +SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*); | |
3411 | + | |
3412 | +/* | |
3413 | +** CAPI3REF: Function Auxiliary Data {H16270} <S20200> | |
1780 | 3414 | ** |
1781 | 3415 | ** The following two functions may be used by scalar SQL functions to |
1782 | -** associate meta-data with argument values. If the same value is passed to | |
3416 | +** associate metadata with argument values. If the same value is passed to | |
1783 | 3417 | ** multiple invocations of the same SQL function during query execution, under |
1784 | -** some circumstances the associated meta-data may be preserved. This may | |
3418 | +** some circumstances the associated metadata may be preserved. This may | |
1785 | 3419 | ** be used, for example, to add a regular-expression matching scalar |
1786 | 3420 | ** function. The compiled version of the regular expression is stored as |
1787 | -** meta-data associated with the SQL value passed as the regular expression | |
3421 | +** metadata associated with the SQL value passed as the regular expression | |
1788 | 3422 | ** pattern. The compiled regular expression can be reused on multiple |
1789 | 3423 | ** invocations of the same function so that the original pattern string |
1790 | 3424 | ** does not need to be recompiled on each invocation. |
1791 | 3425 | ** |
1792 | -** The sqlite3_get_auxdata() interface returns a pointer to the meta-data | |
1793 | -** associated with the Nth argument value to the current SQL function | |
1794 | -** call, where N is the second parameter. If no meta-data has been set for | |
1795 | -** that value, then a NULL pointer is returned. | |
1796 | -** | |
1797 | -** The sqlite3_set_auxdata() is used to associate meta-data with an SQL | |
1798 | -** function argument. The third parameter is a pointer to the meta-data | |
1799 | -** to be associated with the Nth user function argument value. The fourth | |
1800 | -** parameter specifies a destructor that will be called on the meta- | |
1801 | -** data pointer to release it when it is no longer required. If the | |
1802 | -** destructor is NULL, it is not invoked. | |
1803 | -** | |
1804 | -** In practice, meta-data is preserved between function calls for | |
3426 | +** The sqlite3_get_auxdata() interface returns a pointer to the metadata | |
3427 | +** associated by the sqlite3_set_auxdata() function with the Nth argument | |
3428 | +** value to the application-defined function. If no metadata has been ever | |
3429 | +** been set for the Nth argument of the function, or if the corresponding | |
3430 | +** function parameter has changed since the meta-data was set, | |
3431 | +** then sqlite3_get_auxdata() returns a NULL pointer. | |
3432 | +** | |
3433 | +** The sqlite3_set_auxdata() interface saves the metadata | |
3434 | +** pointed to by its 3rd parameter as the metadata for the N-th | |
3435 | +** argument of the application-defined function. Subsequent | |
3436 | +** calls to sqlite3_get_auxdata() might return this data, if it has | |
3437 | +** not been destroyed. | |
3438 | +** If it is not NULL, SQLite will invoke the destructor | |
3439 | +** function given by the 4th parameter to sqlite3_set_auxdata() on | |
3440 | +** the metadata when the corresponding function parameter changes | |
3441 | +** or when the SQL statement completes, whichever comes first. | |
3442 | +** | |
3443 | +** SQLite is free to call the destructor and drop metadata on any | |
3444 | +** parameter of any function at any time. The only guarantee is that | |
3445 | +** the destructor will be called before the metadata is dropped. | |
3446 | +** | |
3447 | +** In practice, metadata is preserved between function calls for | |
1805 | 3448 | ** expressions that are constant at compile time. This includes literal |
1806 | 3449 | ** values and SQL variables. |
3450 | +** | |
3451 | +** These routines must be called from the same thread in which | |
3452 | +** the SQL function is running. | |
3453 | +** | |
3454 | +** Requirements: | |
3455 | +** [H16272] [H16274] [H16276] [H16277] [H16278] [H16279] | |
1807 | 3456 | */ |
1808 | -void *sqlite3_get_auxdata(sqlite3_context*, int); | |
1809 | -void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*)); | |
3457 | +SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N); | |
3458 | +SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*)); | |
1810 | 3459 | |
1811 | 3460 | |
1812 | 3461 | /* |
1813 | -** CAPI3REF: Constants Defining Special Destructor Behavior | |
3462 | +** CAPI3REF: Constants Defining Special Destructor Behavior {H10280} <S30100> | |
1814 | 3463 | ** |
1815 | -** These are special value for the destructor that is passed in as the | |
3464 | +** These are special values for the destructor that is passed in as the | |
1816 | 3465 | ** final argument to routines like [sqlite3_result_blob()]. If the destructor |
1817 | 3466 | ** argument is SQLITE_STATIC, it means that the content pointer is constant |
1818 | -** and will never change. It does not need to be destroyed. The | |
3467 | +** and will never change. It does not need to be destroyed. The | |
1819 | 3468 | ** SQLITE_TRANSIENT value means that the content will likely change in |
1820 | 3469 | ** the near future and that SQLite should make its own private copy of |
1821 | 3470 | ** the content before returning. |
@@ -1828,94 +3477,190 @@ typedef void (*sqlite3_destructor_type)(void*); | ||
1828 | 3477 | #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) |
1829 | 3478 | |
1830 | 3479 | /* |
1831 | -** CAPI3REF: Setting The Result Of An SQL Function | |
3480 | +** CAPI3REF: Setting The Result Of An SQL Function {H16400} <S20200> | |
1832 | 3481 | ** |
1833 | 3482 | ** These routines are used by the xFunc or xFinal callbacks that |
1834 | 3483 | ** implement SQL functions and aggregates. See |
1835 | 3484 | ** [sqlite3_create_function()] and [sqlite3_create_function16()] |
1836 | 3485 | ** for additional information. |
1837 | 3486 | ** |
1838 | -** These functions work very much like the | |
1839 | -** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used | |
1840 | -** to bind values to host parameters in prepared statements. | |
1841 | -** Refer to the | |
1842 | -** [sqlite3_bind_blob | sqlite3_bind_* documentation] for | |
1843 | -** additional information. | |
3487 | +** These functions work very much like the [parameter binding] family of | |
3488 | +** functions used to bind values to host parameters in prepared statements. | |
3489 | +** Refer to the [SQL parameter] documentation for additional information. | |
3490 | +** | |
3491 | +** The sqlite3_result_blob() interface sets the result from | |
3492 | +** an application-defined function to be the BLOB whose content is pointed | |
3493 | +** to by the second parameter and which is N bytes long where N is the | |
3494 | +** third parameter. | |
3495 | +** | |
3496 | +** The sqlite3_result_zeroblob() interfaces set the result of | |
3497 | +** the application-defined function to be a BLOB containing all zero | |
3498 | +** bytes and N bytes in size, where N is the value of the 2nd parameter. | |
3499 | +** | |
3500 | +** The sqlite3_result_double() interface sets the result from | |
3501 | +** an application-defined function to be a floating point value specified | |
3502 | +** by its 2nd argument. | |
1844 | 3503 | ** |
1845 | 3504 | ** The sqlite3_result_error() and sqlite3_result_error16() functions |
1846 | -** cause the implemented SQL function to throw an exception. The | |
1847 | -** parameter to sqlite3_result_error() or sqlite3_result_error16() | |
1848 | -** is the text of an error message. | |
1849 | -** | |
1850 | -** The sqlite3_result_toobig() cause the function implementation | |
1851 | -** to throw and error indicating that a string or BLOB is to long | |
1852 | -** to represent. | |
1853 | -*/ | |
1854 | -void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); | |
1855 | -void sqlite3_result_double(sqlite3_context*, double); | |
1856 | -void sqlite3_result_error(sqlite3_context*, const char*, int); | |
1857 | -void sqlite3_result_error16(sqlite3_context*, const void*, int); | |
1858 | -void sqlite3_result_error_toobig(sqlite3_context*); | |
1859 | -void sqlite3_result_int(sqlite3_context*, int); | |
1860 | -void sqlite3_result_int64(sqlite3_context*, sqlite_int64); | |
1861 | -void sqlite3_result_null(sqlite3_context*); | |
1862 | -void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); | |
1863 | -void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); | |
1864 | -void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); | |
1865 | -void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); | |
1866 | -void sqlite3_result_value(sqlite3_context*, sqlite3_value*); | |
1867 | -void sqlite3_result_zeroblob(sqlite3_context*, int n); | |
1868 | - | |
1869 | -/* | |
1870 | -** CAPI3REF: Define New Collating Sequences | |
3505 | +** cause the implemented SQL function to throw an exception. | |
3506 | +** SQLite uses the string pointed to by the | |
3507 | +** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16() | |
3508 | +** as the text of an error message. SQLite interprets the error | |
3509 | +** message string from sqlite3_result_error() as UTF-8. SQLite | |
3510 | +** interprets the string from sqlite3_result_error16() as UTF-16 in native | |
3511 | +** byte order. If the third parameter to sqlite3_result_error() | |
3512 | +** or sqlite3_result_error16() is negative then SQLite takes as the error | |
3513 | +** message all text up through the first zero character. | |
3514 | +** If the third parameter to sqlite3_result_error() or | |
3515 | +** sqlite3_result_error16() is non-negative then SQLite takes that many | |
3516 | +** bytes (not characters) from the 2nd parameter as the error message. | |
3517 | +** The sqlite3_result_error() and sqlite3_result_error16() | |
3518 | +** routines make a private copy of the error message text before | |
3519 | +** they return. Hence, the calling function can deallocate or | |
3520 | +** modify the text after they return without harm. | |
3521 | +** The sqlite3_result_error_code() function changes the error code | |
3522 | +** returned by SQLite as a result of an error in a function. By default, | |
3523 | +** the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error() | |
3524 | +** or sqlite3_result_error16() resets the error code to SQLITE_ERROR. | |
3525 | +** | |
3526 | +** The sqlite3_result_toobig() interface causes SQLite to throw an error | |
3527 | +** indicating that a string or BLOB is to long to represent. | |
3528 | +** | |
3529 | +** The sqlite3_result_nomem() interface causes SQLite to throw an error | |
3530 | +** indicating that a memory allocation failed. | |
3531 | +** | |
3532 | +** The sqlite3_result_int() interface sets the return value | |
3533 | +** of the application-defined function to be the 32-bit signed integer | |
3534 | +** value given in the 2nd argument. | |
3535 | +** The sqlite3_result_int64() interface sets the return value | |
3536 | +** of the application-defined function to be the 64-bit signed integer | |
3537 | +** value given in the 2nd argument. | |
3538 | +** | |
3539 | +** The sqlite3_result_null() interface sets the return value | |
3540 | +** of the application-defined function to be NULL. | |
3541 | +** | |
3542 | +** The sqlite3_result_text(), sqlite3_result_text16(), | |
3543 | +** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces | |
3544 | +** set the return value of the application-defined function to be | |
3545 | +** a text string which is represented as UTF-8, UTF-16 native byte order, | |
3546 | +** UTF-16 little endian, or UTF-16 big endian, respectively. | |
3547 | +** SQLite takes the text result from the application from | |
3548 | +** the 2nd parameter of the sqlite3_result_text* interfaces. | |
3549 | +** If the 3rd parameter to the sqlite3_result_text* interfaces | |
3550 | +** is negative, then SQLite takes result text from the 2nd parameter | |
3551 | +** through the first zero character. | |
3552 | +** If the 3rd parameter to the sqlite3_result_text* interfaces | |
3553 | +** is non-negative, then as many bytes (not characters) of the text | |
3554 | +** pointed to by the 2nd parameter are taken as the application-defined | |
3555 | +** function result. | |
3556 | +** If the 4th parameter to the sqlite3_result_text* interfaces | |
3557 | +** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that | |
3558 | +** function as the destructor on the text or BLOB result when it has | |
3559 | +** finished using that result. | |
3560 | +** If the 4th parameter to the sqlite3_result_text* interfaces or to | |
3561 | +** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite | |
3562 | +** assumes that the text or BLOB result is in constant space and does not | |
3563 | +** copy the content of the parameter nor call a destructor on the content | |
3564 | +** when it has finished using that result. | |
3565 | +** If the 4th parameter to the sqlite3_result_text* interfaces | |
3566 | +** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT | |
3567 | +** then SQLite makes a copy of the result into space obtained from | |
3568 | +** from [sqlite3_malloc()] before it returns. | |
3569 | +** | |
3570 | +** The sqlite3_result_value() interface sets the result of | |
3571 | +** the application-defined function to be a copy the | |
3572 | +** [unprotected sqlite3_value] object specified by the 2nd parameter. The | |
3573 | +** sqlite3_result_value() interface makes a copy of the [sqlite3_value] | |
3574 | +** so that the [sqlite3_value] specified in the parameter may change or | |
3575 | +** be deallocated after sqlite3_result_value() returns without harm. | |
3576 | +** A [protected sqlite3_value] object may always be used where an | |
3577 | +** [unprotected sqlite3_value] object is required, so either | |
3578 | +** kind of [sqlite3_value] object can be used with this interface. | |
3579 | +** | |
3580 | +** If these routines are called from within the different thread | |
3581 | +** than the one containing the application-defined function that received | |
3582 | +** the [sqlite3_context] pointer, the results are undefined. | |
3583 | +** | |
3584 | +** Requirements: | |
3585 | +** [H16403] [H16406] [H16409] [H16412] [H16415] [H16418] [H16421] [H16424] | |
3586 | +** [H16427] [H16430] [H16433] [H16436] [H16439] [H16442] [H16445] [H16448] | |
3587 | +** [H16451] [H16454] [H16457] [H16460] [H16463] | |
3588 | +*/ | |
3589 | +SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); | |
3590 | +SQLITE_API void sqlite3_result_double(sqlite3_context*, double); | |
3591 | +SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int); | |
3592 | +SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int); | |
3593 | +SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*); | |
3594 | +SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*); | |
3595 | +SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int); | |
3596 | +SQLITE_API void sqlite3_result_int(sqlite3_context*, int); | |
3597 | +SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); | |
3598 | +SQLITE_API void sqlite3_result_null(sqlite3_context*); | |
3599 | +SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); | |
3600 | +SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); | |
3601 | +SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); | |
3602 | +SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); | |
3603 | +SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*); | |
3604 | +SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n); | |
3605 | + | |
3606 | +/* | |
3607 | +** CAPI3REF: Define New Collating Sequences {H16600} <S20300> | |
1871 | 3608 | ** |
1872 | 3609 | ** These functions are used to add new collation sequences to the |
1873 | -** [sqlite3*] handle specified as the first argument. | |
3610 | +** [database connection] specified as the first argument. | |
1874 | 3611 | ** |
1875 | 3612 | ** The name of the new collation sequence is specified as a UTF-8 string |
1876 | 3613 | ** for sqlite3_create_collation() and sqlite3_create_collation_v2() |
1877 | -** and a UTF-16 string for sqlite3_create_collation16(). In all cases | |
3614 | +** and a UTF-16 string for sqlite3_create_collation16(). In all cases | |
1878 | 3615 | ** the name is passed as the second function argument. |
1879 | 3616 | ** |
1880 | -** The third argument must be one of the constants [SQLITE_UTF8], | |
1881 | -** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied | |
3617 | +** The third argument may be one of the constants [SQLITE_UTF8], | |
3618 | +** [SQLITE_UTF16LE], or [SQLITE_UTF16BE], indicating that the user-supplied | |
1882 | 3619 | ** routine expects to be passed pointers to strings encoded using UTF-8, |
1883 | -** UTF-16 little-endian or UTF-16 big-endian respectively. | |
3620 | +** UTF-16 little-endian, or UTF-16 big-endian, respectively. The | |
3621 | +** third argument might also be [SQLITE_UTF16] to indicate that the routine | |
3622 | +** expects pointers to be UTF-16 strings in the native byte order, or the | |
3623 | +** argument can be [SQLITE_UTF16_ALIGNED] if the | |
3624 | +** the routine expects pointers to 16-bit word aligned strings | |
3625 | +** of UTF-16 in the native byte order. | |
1884 | 3626 | ** |
1885 | 3627 | ** A pointer to the user supplied routine must be passed as the fifth |
1886 | -** argument. If it is NULL, this is the same as deleting the collation | |
1887 | -** sequence (so that SQLite cannot call it anymore). Each time the user | |
1888 | -** supplied function is invoked, it is passed a copy of the void* passed as | |
1889 | -** the fourth argument to sqlite3_create_collation() or | |
1890 | -** sqlite3_create_collation16() as its first parameter. | |
1891 | -** | |
1892 | -** The remaining arguments to the user-supplied routine are two strings, | |
1893 | -** each represented by a [length, data] pair and encoded in the encoding | |
3628 | +** argument. If it is NULL, this is the same as deleting the collation | |
3629 | +** sequence (so that SQLite cannot call it anymore). | |
3630 | +** Each time the application supplied function is invoked, it is passed | |
3631 | +** as its first parameter a copy of the void* passed as the fourth argument | |
3632 | +** to sqlite3_create_collation() or sqlite3_create_collation16(). | |
3633 | +** | |
3634 | +** The remaining arguments to the application-supplied routine are two strings, | |
3635 | +** each represented by a (length, data) pair and encoded in the encoding | |
1894 | 3636 | ** that was passed as the third argument when the collation sequence was |
1895 | -** registered. The user routine should return negative, zero or positive if | |
1896 | -** the first string is less than, equal to, or greater than the second | |
1897 | -** string. i.e. (STRING1 - STRING2). | |
3637 | +** registered. {END} The application defined collation routine should | |
3638 | +** return negative, zero or positive if the first string is less than, | |
3639 | +** equal to, or greater than the second string. i.e. (STRING1 - STRING2). | |
1898 | 3640 | ** |
1899 | 3641 | ** The sqlite3_create_collation_v2() works like sqlite3_create_collation() |
1900 | -** excapt that it takes an extra argument which is a destructor for | |
3642 | +** except that it takes an extra argument which is a destructor for | |
1901 | 3643 | ** the collation. The destructor is called when the collation is |
1902 | 3644 | ** destroyed and is passed a copy of the fourth parameter void* pointer |
1903 | -** of the sqlite3_create_collation_v2(). Collations are destroyed when | |
1904 | -** they are overridden by later calls to the collation creation functions | |
1905 | -** or when the [sqlite3*] database handle is closed using [sqlite3_close()]. | |
3645 | +** of the sqlite3_create_collation_v2(). | |
3646 | +** Collations are destroyed when they are overridden by later calls to the | |
3647 | +** collation creation functions or when the [database connection] is closed | |
3648 | +** using [sqlite3_close()]. | |
3649 | +** | |
3650 | +** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()]. | |
1906 | 3651 | ** |
1907 | -** The sqlite3_create_collation_v2() interface is experimental and | |
1908 | -** subject to change in future releases. The other collation creation | |
1909 | -** functions are stable. | |
3652 | +** Requirements: | |
3653 | +** [H16603] [H16604] [H16606] [H16609] [H16612] [H16615] [H16618] [H16621] | |
3654 | +** [H16624] [H16627] [H16630] | |
1910 | 3655 | */ |
1911 | -int sqlite3_create_collation( | |
3656 | +SQLITE_API int sqlite3_create_collation( | |
1912 | 3657 | sqlite3*, |
1913 | 3658 | const char *zName, |
1914 | 3659 | int eTextRep, |
1915 | 3660 | void*, |
1916 | 3661 | int(*xCompare)(void*,int,const void*,int,const void*) |
1917 | 3662 | ); |
1918 | -int sqlite3_create_collation_v2( | |
3663 | +SQLITE_API int sqlite3_create_collation_v2( | |
1919 | 3664 | sqlite3*, |
1920 | 3665 | const char *zName, |
1921 | 3666 | int eTextRep, |
@@ -1923,46 +3668,49 @@ int sqlite3_create_collation_v2( | ||
1923 | 3668 | int(*xCompare)(void*,int,const void*,int,const void*), |
1924 | 3669 | void(*xDestroy)(void*) |
1925 | 3670 | ); |
1926 | -int sqlite3_create_collation16( | |
3671 | +SQLITE_API int sqlite3_create_collation16( | |
1927 | 3672 | sqlite3*, |
1928 | - const char *zName, | |
3673 | + const void *zName, | |
1929 | 3674 | int eTextRep, |
1930 | 3675 | void*, |
1931 | 3676 | int(*xCompare)(void*,int,const void*,int,const void*) |
1932 | 3677 | ); |
1933 | 3678 | |
1934 | 3679 | /* |
1935 | -** CAPI3REF: Collation Needed Callbacks | |
3680 | +** CAPI3REF: Collation Needed Callbacks {H16700} <S20300> | |
1936 | 3681 | ** |
1937 | 3682 | ** To avoid having to register all collation sequences before a database |
1938 | 3683 | ** can be used, a single callback function may be registered with the |
1939 | -** database handle to be called whenever an undefined collation sequence is | |
1940 | -** required. | |
3684 | +** [database connection] to be called whenever an undefined collation | |
3685 | +** sequence is required. | |
1941 | 3686 | ** |
1942 | 3687 | ** If the function is registered using the sqlite3_collation_needed() API, |
1943 | 3688 | ** then it is passed the names of undefined collation sequences as strings |
1944 | -** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names | |
1945 | -** are passed as UTF-16 in machine native byte order. A call to either | |
1946 | -** function replaces any existing callback. | |
3689 | +** encoded in UTF-8. {H16703} If sqlite3_collation_needed16() is used, | |
3690 | +** the names are passed as UTF-16 in machine native byte order. | |
3691 | +** A call to either function replaces any existing callback. | |
1947 | 3692 | ** |
1948 | 3693 | ** When the callback is invoked, the first argument passed is a copy |
1949 | 3694 | ** of the second argument to sqlite3_collation_needed() or |
1950 | -** sqlite3_collation_needed16(). The second argument is the database | |
1951 | -** handle. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], or | |
1952 | -** [SQLITE_UTF16LE], indicating the most desirable form of the collation | |
1953 | -** sequence function required. The fourth parameter is the name of the | |
3695 | +** sqlite3_collation_needed16(). The second argument is the database | |
3696 | +** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], | |
3697 | +** or [SQLITE_UTF16LE], indicating the most desirable form of the collation | |
3698 | +** sequence function required. The fourth parameter is the name of the | |
1954 | 3699 | ** required collation sequence. |
1955 | 3700 | ** |
1956 | 3701 | ** The callback function should register the desired collation using |
1957 | 3702 | ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or |
1958 | 3703 | ** [sqlite3_create_collation_v2()]. |
3704 | +** | |
3705 | +** Requirements: | |
3706 | +** [H16702] [H16704] [H16706] | |
1959 | 3707 | */ |
1960 | -int sqlite3_collation_needed( | |
3708 | +SQLITE_API int sqlite3_collation_needed( | |
1961 | 3709 | sqlite3*, |
1962 | 3710 | void*, |
1963 | 3711 | void(*)(void*,sqlite3*,int eTextRep,const char*) |
1964 | 3712 | ); |
1965 | -int sqlite3_collation_needed16( | |
3713 | +SQLITE_API int sqlite3_collation_needed16( | |
1966 | 3714 | sqlite3*, |
1967 | 3715 | void*, |
1968 | 3716 | void(*)(void*,sqlite3*,int eTextRep,const void*) |
@@ -1975,7 +3723,7 @@ int sqlite3_collation_needed16( | ||
1975 | 3723 | ** The code to implement this API is not available in the public release |
1976 | 3724 | ** of SQLite. |
1977 | 3725 | */ |
1978 | -int sqlite3_key( | |
3726 | +SQLITE_API int sqlite3_key( | |
1979 | 3727 | sqlite3 *db, /* Database to be rekeyed */ |
1980 | 3728 | const void *pKey, int nKey /* The key */ |
1981 | 3729 | ); |
@@ -1988,265 +3736,348 @@ int sqlite3_key( | ||
1988 | 3736 | ** The code to implement this API is not available in the public release |
1989 | 3737 | ** of SQLite. |
1990 | 3738 | */ |
1991 | -int sqlite3_rekey( | |
3739 | +SQLITE_API int sqlite3_rekey( | |
1992 | 3740 | sqlite3 *db, /* Database to be rekeyed */ |
1993 | 3741 | const void *pKey, int nKey /* The new key */ |
1994 | 3742 | ); |
1995 | 3743 | |
1996 | 3744 | /* |
1997 | -** CAPI3REF: Suspend Execution For A Short Time | |
3745 | +** CAPI3REF: Suspend Execution For A Short Time {H10530} <S40410> | |
1998 | 3746 | ** |
1999 | -** This function causes the current thread to suspend execution | |
2000 | -** a number of milliseconds specified in its parameter. | |
3747 | +** The sqlite3_sleep() function causes the current thread to suspend execution | |
3748 | +** for at least a number of milliseconds specified in its parameter. | |
2001 | 3749 | ** |
2002 | -** If the operating system does not support sleep requests with | |
2003 | -** millisecond time resolution, then the time will be rounded up to | |
2004 | -** the nearest second. The number of milliseconds of sleep actually | |
3750 | +** If the operating system does not support sleep requests with | |
3751 | +** millisecond time resolution, then the time will be rounded up to | |
3752 | +** the nearest second. The number of milliseconds of sleep actually | |
2005 | 3753 | ** requested from the operating system is returned. |
3754 | +** | |
3755 | +** SQLite implements this interface by calling the xSleep() | |
3756 | +** method of the default [sqlite3_vfs] object. | |
3757 | +** | |
3758 | +** Requirements: [H10533] [H10536] | |
2006 | 3759 | */ |
2007 | -int sqlite3_sleep(int); | |
3760 | +SQLITE_API int sqlite3_sleep(int); | |
2008 | 3761 | |
2009 | 3762 | /* |
2010 | -** CAPI3REF: Name Of The Folder Holding Temporary Files | |
3763 | +** CAPI3REF: Name Of The Folder Holding Temporary Files {H10310} <S20000> | |
2011 | 3764 | ** |
2012 | 3765 | ** If this global variable is made to point to a string which is |
2013 | -** the name of a folder (a.ka. directory), then all temporary files | |
3766 | +** the name of a folder (a.k.a. directory), then all temporary files | |
2014 | 3767 | ** created by SQLite will be placed in that directory. If this variable |
2015 | -** is NULL pointer, then SQLite does a search for an appropriate temporary | |
2016 | -** file directory. | |
2017 | -** | |
2018 | -** Once [sqlite3_open()] has been called, changing this variable will | |
2019 | -** invalidate the current temporary database, if any. Generally speaking, | |
2020 | -** it is not safe to invoke this routine after [sqlite3_open()] has | |
2021 | -** been called. | |
3768 | +** is a NULL pointer, then SQLite performs a search for an appropriate | |
3769 | +** temporary file directory. | |
3770 | +** | |
3771 | +** It is not safe to read or modify this variable in more than one | |
3772 | +** thread at a time. It is not safe to read or modify this variable | |
3773 | +** if a [database connection] is being used at the same time in a separate | |
3774 | +** thread. | |
3775 | +** It is intended that this variable be set once | |
3776 | +** as part of process initialization and before any SQLite interface | |
3777 | +** routines have been called and that this variable remain unchanged | |
3778 | +** thereafter. | |
3779 | +** | |
3780 | +** The [temp_store_directory pragma] may modify this variable and cause | |
3781 | +** it to point to memory obtained from [sqlite3_malloc]. Furthermore, | |
3782 | +** the [temp_store_directory pragma] always assumes that any string | |
3783 | +** that this variable points to is held in memory obtained from | |
3784 | +** [sqlite3_malloc] and the pragma may attempt to free that memory | |
3785 | +** using [sqlite3_free]. | |
3786 | +** Hence, if this variable is modified directly, either it should be | |
3787 | +** made NULL or made to point to memory obtained from [sqlite3_malloc] | |
3788 | +** or else the use of the [temp_store_directory pragma] should be avoided. | |
2022 | 3789 | */ |
2023 | -extern char *sqlite3_temp_directory; | |
3790 | +SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory; | |
2024 | 3791 | |
2025 | 3792 | /* |
2026 | -** CAPI3REF: Test To See If The Databse Is In Auto-Commit Mode | |
2027 | -** | |
2028 | -** Test to see whether or not the database connection is in autocommit | |
2029 | -** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on | |
2030 | -** by default. Autocommit is disabled by a BEGIN statement and reenabled | |
2031 | -** by the next COMMIT or ROLLBACK. | |
3793 | +** CAPI3REF: Test For Auto-Commit Mode {H12930} <S60200> | |
3794 | +** KEYWORDS: {autocommit mode} | |
3795 | +** | |
3796 | +** The sqlite3_get_autocommit() interface returns non-zero or | |
3797 | +** zero if the given database connection is or is not in autocommit mode, | |
3798 | +** respectively. Autocommit mode is on by default. | |
3799 | +** Autocommit mode is disabled by a [BEGIN] statement. | |
3800 | +** Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK]. | |
3801 | +** | |
3802 | +** If certain kinds of errors occur on a statement within a multi-statement | |
3803 | +** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR], | |
3804 | +** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the | |
3805 | +** transaction might be rolled back automatically. The only way to | |
3806 | +** find out whether SQLite automatically rolled back the transaction after | |
3807 | +** an error is to use this function. | |
3808 | +** | |
3809 | +** If another thread changes the autocommit status of the database | |
3810 | +** connection while this routine is running, then the return value | |
3811 | +** is undefined. | |
3812 | +** | |
3813 | +** Requirements: [H12931] [H12932] [H12933] [H12934] | |
2032 | 3814 | */ |
2033 | -int sqlite3_get_autocommit(sqlite3*); | |
3815 | +SQLITE_API int sqlite3_get_autocommit(sqlite3*); | |
2034 | 3816 | |
2035 | 3817 | /* |
2036 | -** CAPI3REF: Find The Database Handle Associated With A Prepared Statement | |
3818 | +** CAPI3REF: Find The Database Handle Of A Prepared Statement {H13120} <S60600> | |
2037 | 3819 | ** |
2038 | -** Return the [sqlite3*] database handle to which a | |
2039 | -** [sqlite3_stmt | prepared statement] belongs. | |
2040 | -** This is the same database handle that was | |
2041 | -** the first argument to the [sqlite3_prepare_v2()] or its variants | |
2042 | -** that was used to create the statement in the first place. | |
3820 | +** The sqlite3_db_handle interface returns the [database connection] handle | |
3821 | +** to which a [prepared statement] belongs. The [database connection] | |
3822 | +** returned by sqlite3_db_handle is the same [database connection] that was the first argument | |
3823 | +** to the [sqlite3_prepare_v2()] call (or its variants) that was used to | |
3824 | +** create the statement in the first place. | |
3825 | +** | |
3826 | +** Requirements: [H13123] | |
2043 | 3827 | */ |
2044 | -sqlite3 *sqlite3_db_handle(sqlite3_stmt*); | |
2045 | - | |
3828 | +SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*); | |
2046 | 3829 | |
2047 | 3830 | /* |
2048 | -** CAPI3REF: Commit And Rollback Notification Callbacks | |
3831 | +** CAPI3REF: Find the next prepared statement {H13140} <S60600> | |
2049 | 3832 | ** |
2050 | -** These routines | |
2051 | -** register callback functions to be invoked whenever a transaction | |
2052 | -** is committed or rolled back. The pArg argument is passed through | |
2053 | -** to the callback. If the callback on a commit hook function | |
2054 | -** returns non-zero, then the commit is converted into a rollback. | |
3833 | +** This interface returns a pointer to the next [prepared statement] after | |
3834 | +** pStmt associated with the [database connection] pDb. If pStmt is NULL | |
3835 | +** then this interface returns a pointer to the first prepared statement | |
3836 | +** associated with the database connection pDb. If no prepared statement | |
3837 | +** satisfies the conditions of this routine, it returns NULL. | |
2055 | 3838 | ** |
2056 | -** If another function was previously registered, its pArg value is returned. | |
2057 | -** Otherwise NULL is returned. | |
3839 | +** The [database connection] pointer D in a call to | |
3840 | +** [sqlite3_next_stmt(D,S)] must refer to an open database | |
3841 | +** connection and in particular must not be a NULL pointer. | |
3842 | +** | |
3843 | +** Requirements: [H13143] [H13146] [H13149] [H13152] | |
3844 | +*/ | |
3845 | +SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt); | |
3846 | + | |
3847 | +/* | |
3848 | +** CAPI3REF: Commit And Rollback Notification Callbacks {H12950} <S60400> | |
3849 | +** | |
3850 | +** The sqlite3_commit_hook() interface registers a callback | |
3851 | +** function to be invoked whenever a transaction is [COMMIT | committed]. | |
3852 | +** Any callback set by a previous call to sqlite3_commit_hook() | |
3853 | +** for the same database connection is overridden. | |
3854 | +** The sqlite3_rollback_hook() interface registers a callback | |
3855 | +** function to be invoked whenever a transaction is [ROLLBACK | rolled back]. | |
3856 | +** Any callback set by a previous call to sqlite3_commit_hook() | |
3857 | +** for the same database connection is overridden. | |
3858 | +** The pArg argument is passed through to the callback. | |
3859 | +** If the callback on a commit hook function returns non-zero, | |
3860 | +** then the commit is converted into a rollback. | |
3861 | +** | |
3862 | +** If another function was previously registered, its | |
3863 | +** pArg value is returned. Otherwise NULL is returned. | |
3864 | +** | |
3865 | +** The callback implementation must not do anything that will modify | |
3866 | +** the database connection that invoked the callback. Any actions | |
3867 | +** to modify the database connection must be deferred until after the | |
3868 | +** completion of the [sqlite3_step()] call that triggered the commit | |
3869 | +** or rollback hook in the first place. | |
3870 | +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their | |
3871 | +** database connections for the meaning of "modify" in this paragraph. | |
2058 | 3872 | ** |
2059 | 3873 | ** Registering a NULL function disables the callback. |
2060 | 3874 | ** |
2061 | -** For the purposes of this API, a transaction is said to have been | |
2062 | -** rolled back if an explicit "ROLLBACK" statement is executed, or | |
2063 | -** an error or constraint causes an implicit rollback to occur. The | |
2064 | -** callback is not invoked if a transaction is automatically rolled | |
2065 | -** back because the database connection is closed. | |
3875 | +** When the commit hook callback routine returns zero, the [COMMIT] | |
3876 | +** operation is allowed to continue normally. If the commit hook | |
3877 | +** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK]. | |
3878 | +** The rollback hook is invoked on a rollback that results from a commit | |
3879 | +** hook returning non-zero, just as it would be with any other rollback. | |
2066 | 3880 | ** |
2067 | -** These are experimental interfaces and are subject to change. | |
3881 | +** For the purposes of this API, a transaction is said to have been | |
3882 | +** rolled back if an explicit "ROLLBACK" statement is executed, or | |
3883 | +** an error or constraint causes an implicit rollback to occur. | |
3884 | +** The rollback callback is not invoked if a transaction is | |
3885 | +** automatically rolled back because the database connection is closed. | |
3886 | +** The rollback callback is not invoked if a transaction is | |
3887 | +** rolled back because a commit callback returned non-zero. | |
3888 | +** <todo> Check on this </todo> | |
3889 | +** | |
3890 | +** See also the [sqlite3_update_hook()] interface. | |
3891 | +** | |
3892 | +** Requirements: | |
3893 | +** [H12951] [H12952] [H12953] [H12954] [H12955] | |
3894 | +** [H12961] [H12962] [H12963] [H12964] | |
2068 | 3895 | */ |
2069 | -void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); | |
2070 | -void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); | |
3896 | +SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); | |
3897 | +SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); | |
2071 | 3898 | |
2072 | 3899 | /* |
2073 | -** CAPI3REF: Data Change Notification Callbacks | |
2074 | -** | |
2075 | -** Register a callback function with the database connection identified by the | |
2076 | -** first argument to be invoked whenever a row is updated, inserted or deleted. | |
2077 | -** Any callback set by a previous call to this function for the same | |
2078 | -** database connection is overridden. | |
2079 | -** | |
2080 | -** The second argument is a pointer to the function to invoke when a | |
2081 | -** row is updated, inserted or deleted. The first argument to the callback is | |
2082 | -** a copy of the third argument to sqlite3_update_hook(). The second callback | |
2083 | -** argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending | |
2084 | -** on the operation that caused the callback to be invoked. The third and | |
2085 | -** fourth arguments to the callback contain pointers to the database and | |
2086 | -** table name containing the affected row. The final callback parameter is | |
2087 | -** the rowid of the row. In the case of an update, this is the rowid after | |
2088 | -** the update takes place. | |
3900 | +** CAPI3REF: Data Change Notification Callbacks {H12970} <S60400> | |
3901 | +** | |
3902 | +** The sqlite3_update_hook() interface registers a callback function | |
3903 | +** with the [database connection] identified by the first argument | |
3904 | +** to be invoked whenever a row is updated, inserted or deleted. | |
3905 | +** Any callback set by a previous call to this function | |
3906 | +** for the same database connection is overridden. | |
3907 | +** | |
3908 | +** The second argument is a pointer to the function to invoke when a | |
3909 | +** row is updated, inserted or deleted. | |
3910 | +** The first argument to the callback is a copy of the third argument | |
3911 | +** to sqlite3_update_hook(). | |
3912 | +** The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE], | |
3913 | +** or [SQLITE_UPDATE], depending on the operation that caused the callback | |
3914 | +** to be invoked. | |
3915 | +** The third and fourth arguments to the callback contain pointers to the | |
3916 | +** database and table name containing the affected row. | |
3917 | +** The final callback parameter is the [rowid] of the row. | |
3918 | +** In the case of an update, this is the [rowid] after the update takes place. | |
2089 | 3919 | ** |
2090 | 3920 | ** The update hook is not invoked when internal system tables are |
2091 | 3921 | ** modified (i.e. sqlite_master and sqlite_sequence). |
2092 | 3922 | ** |
2093 | -** If another function was previously registered, its pArg value is returned. | |
2094 | -** Otherwise NULL is returned. | |
3923 | +** In the current implementation, the update hook | |
3924 | +** is not invoked when duplication rows are deleted because of an | |
3925 | +** [ON CONFLICT | ON CONFLICT REPLACE] clause. Nor is the update hook | |
3926 | +** invoked when rows are deleted using the [truncate optimization]. | |
3927 | +** The exceptions defined in this paragraph might change in a future | |
3928 | +** release of SQLite. | |
3929 | +** | |
3930 | +** The update hook implementation must not do anything that will modify | |
3931 | +** the database connection that invoked the update hook. Any actions | |
3932 | +** to modify the database connection must be deferred until after the | |
3933 | +** completion of the [sqlite3_step()] call that triggered the update hook. | |
3934 | +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their | |
3935 | +** database connections for the meaning of "modify" in this paragraph. | |
3936 | +** | |
3937 | +** If another function was previously registered, its pArg value | |
3938 | +** is returned. Otherwise NULL is returned. | |
3939 | +** | |
3940 | +** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()] | |
3941 | +** interfaces. | |
3942 | +** | |
3943 | +** Requirements: | |
3944 | +** [H12971] [H12973] [H12975] [H12977] [H12979] [H12981] [H12983] [H12986] | |
2095 | 3945 | */ |
2096 | -void *sqlite3_update_hook( | |
3946 | +SQLITE_API void *sqlite3_update_hook( | |
2097 | 3947 | sqlite3*, |
2098 | - void(*)(void *,int ,char const *,char const *,sqlite_int64), | |
3948 | + void(*)(void *,int ,char const *,char const *,sqlite3_int64), | |
2099 | 3949 | void* |
2100 | 3950 | ); |
2101 | 3951 | |
2102 | 3952 | /* |
2103 | -** CAPI3REF: Enable Or Disable Shared Pager Cache | |
3953 | +** CAPI3REF: Enable Or Disable Shared Pager Cache {H10330} <S30900> | |
3954 | +** KEYWORDS: {shared cache} | |
2104 | 3955 | ** |
2105 | 3956 | ** This routine enables or disables the sharing of the database cache |
2106 | -** and schema data structures between connections to the same database. | |
2107 | -** Sharing is enabled if the argument is true and disabled if the argument | |
2108 | -** is false. | |
2109 | -** | |
2110 | -** Cache sharing is enabled and disabled on a thread-by-thread basis. | |
2111 | -** Each call to this routine enables or disables cache sharing only for | |
2112 | -** connections created in the same thread in which this routine is called. | |
2113 | -** There is no mechanism for sharing cache between database connections | |
2114 | -** running in different threads. | |
2115 | -** | |
2116 | -** Sharing must be disabled prior to shutting down a thread or else | |
2117 | -** the thread will leak memory. Call this routine with an argument of | |
2118 | -** 0 to turn off sharing. Or use the sqlite3_thread_cleanup() API. | |
2119 | -** | |
2120 | -** This routine must not be called when any database connections | |
2121 | -** are active in the current thread. Enabling or disabling shared | |
2122 | -** cache while there are active database connections will result | |
2123 | -** in memory corruption. | |
2124 | -** | |
2125 | -** When the shared cache is enabled, the | |
2126 | -** following routines must always be called from the same thread: | |
2127 | -** [sqlite3_open()], [sqlite3_prepare_v2()], [sqlite3_step()], | |
2128 | -** [sqlite3_reset()], [sqlite3_finalize()], and [sqlite3_close()]. | |
2129 | -** This is due to the fact that the shared cache makes use of | |
2130 | -** thread-specific storage so that it will be available for sharing | |
2131 | -** with other connections. | |
3957 | +** and schema data structures between [database connection | connections] | |
3958 | +** to the same database. Sharing is enabled if the argument is true | |
3959 | +** and disabled if the argument is false. | |
3960 | +** | |
3961 | +** Cache sharing is enabled and disabled for an entire process. | |
3962 | +** This is a change as of SQLite version 3.5.0. In prior versions of SQLite, | |
3963 | +** sharing was enabled or disabled for each thread separately. | |
3964 | +** | |
3965 | +** The cache sharing mode set by this interface effects all subsequent | |
3966 | +** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. | |
3967 | +** Existing database connections continue use the sharing mode | |
3968 | +** that was in effect at the time they were opened. | |
2132 | 3969 | ** |
2133 | 3970 | ** Virtual tables cannot be used with a shared cache. When shared |
2134 | -** cache is enabled, the sqlite3_create_module() API used to register | |
3971 | +** cache is enabled, the [sqlite3_create_module()] API used to register | |
2135 | 3972 | ** virtual tables will always return an error. |
2136 | 3973 | ** |
2137 | -** This routine returns [SQLITE_OK] if shared cache was | |
2138 | -** enabled or disabled successfully. An [SQLITE_ERROR | error code] | |
2139 | -** is returned otherwise. | |
3974 | +** This routine returns [SQLITE_OK] if shared cache was enabled or disabled | |
3975 | +** successfully. An [error code] is returned otherwise. | |
3976 | +** | |
3977 | +** Shared cache is disabled by default. But this might change in | |
3978 | +** future releases of SQLite. Applications that care about shared | |
3979 | +** cache setting should set it explicitly. | |
3980 | +** | |
3981 | +** See Also: [SQLite Shared-Cache Mode] | |
2140 | 3982 | ** |
2141 | -** Shared cache is disabled by default for backward compatibility. | |
3983 | +** Requirements: [H10331] [H10336] [H10337] [H10339] | |
2142 | 3984 | */ |
2143 | -int sqlite3_enable_shared_cache(int); | |
3985 | +SQLITE_API int sqlite3_enable_shared_cache(int); | |
2144 | 3986 | |
2145 | 3987 | /* |
2146 | -** CAPI3REF: Attempt To Free Heap Memory | |
3988 | +** CAPI3REF: Attempt To Free Heap Memory {H17340} <S30220> | |
2147 | 3989 | ** |
2148 | -** Attempt to free N bytes of heap memory by deallocating non-essential | |
2149 | -** memory allocations held by the database library (example: memory | |
2150 | -** used to cache database pages to improve performance). | |
3990 | +** The sqlite3_release_memory() interface attempts to free N bytes | |
3991 | +** of heap memory by deallocating non-essential memory allocations | |
3992 | +** held by the database library. {END} Memory used to cache database | |
3993 | +** pages to improve performance is an example of non-essential memory. | |
3994 | +** sqlite3_release_memory() returns the number of bytes actually freed, | |
3995 | +** which might be more or less than the amount requested. | |
2151 | 3996 | ** |
2152 | -** This function is not a part of standard builds. It is only created | |
2153 | -** if SQLite is compiled with the SQLITE_ENABLE_MEMORY_MANAGEMENT macro. | |
3997 | +** Requirements: [H17341] [H17342] | |
2154 | 3998 | */ |
2155 | -int sqlite3_release_memory(int); | |
3999 | +SQLITE_API int sqlite3_release_memory(int); | |
2156 | 4000 | |
2157 | 4001 | /* |
2158 | -** CAPI3REF: Impose A Limit On Heap Size | |
4002 | +** CAPI3REF: Impose A Limit On Heap Size {H17350} <S30220> | |
2159 | 4003 | ** |
2160 | -** Place a "soft" limit on the amount of heap memory that may be allocated by | |
2161 | -** SQLite within the current thread. If an internal allocation is requested | |
2162 | -** that would exceed the specified limit, [sqlite3_release_memory()] is invoked | |
2163 | -** one or more times to free up some space before the allocation is made. | |
4004 | +** The sqlite3_soft_heap_limit() interface places a "soft" limit | |
4005 | +** on the amount of heap memory that may be allocated by SQLite. | |
4006 | +** If an internal allocation is requested that would exceed the | |
4007 | +** soft heap limit, [sqlite3_release_memory()] is invoked one or | |
4008 | +** more times to free up some space before the allocation is performed. | |
2164 | 4009 | ** |
2165 | -** The limit is called "soft", because if [sqlite3_release_memory()] cannot free | |
2166 | -** sufficient memory to prevent the limit from being exceeded, the memory is | |
2167 | -** allocated anyway and the current operation proceeds. | |
2168 | -** | |
2169 | -** Prior to shutting down a thread sqlite3_soft_heap_limit() must be set to | |
2170 | -** zero (the default) or else the thread will leak memory. Alternatively, use | |
2171 | -** the [sqlite3_thread_cleanup()] API. | |
4010 | +** The limit is called "soft", because if [sqlite3_release_memory()] | |
4011 | +** cannot free sufficient memory to prevent the limit from being exceeded, | |
4012 | +** the memory is allocated anyway and the current operation proceeds. | |
2172 | 4013 | ** |
2173 | 4014 | ** A negative or zero value for N means that there is no soft heap limit and |
2174 | -** [sqlite3_release_memory()] will only be called when memory is exhaused. | |
4015 | +** [sqlite3_release_memory()] will only be called when memory is exhausted. | |
2175 | 4016 | ** The default value for the soft heap limit is zero. |
2176 | 4017 | ** |
2177 | -** SQLite makes a best effort to honor the soft heap limit. But if it | |
2178 | -** is unable to reduce memory usage below the soft limit, execution will | |
2179 | -** continue without error or notification. This is why the limit is | |
4018 | +** SQLite makes a best effort to honor the soft heap limit. | |
4019 | +** But if the soft heap limit cannot be honored, execution will | |
4020 | +** continue without error or notification. This is why the limit is | |
2180 | 4021 | ** called a "soft" limit. It is advisory only. |
2181 | 4022 | ** |
2182 | -** This function is only available if the library was compiled with the | |
2183 | -** SQLITE_ENABLE_MEMORY_MANAGEMENT option set. | |
2184 | -** memory-management has been enabled. | |
2185 | -*/ | |
2186 | -void sqlite3_soft_heap_limit(int); | |
2187 | - | |
2188 | -/* | |
2189 | -** CAPI3REF: Clean Up Thread Local Storage | |
2190 | -** | |
2191 | -** This routine makes sure that all thread-local storage has been | |
2192 | -** deallocated for the current thread. | |
4023 | +** Prior to SQLite version 3.5.0, this routine only constrained the memory | |
4024 | +** allocated by a single thread - the same thread in which this routine | |
4025 | +** runs. Beginning with SQLite version 3.5.0, the soft heap limit is | |
4026 | +** applied to all threads. The value specified for the soft heap limit | |
4027 | +** is an upper bound on the total memory allocation for all threads. In | |
4028 | +** version 3.5.0 there is no mechanism for limiting the heap usage for | |
4029 | +** individual threads. | |
2193 | 4030 | ** |
2194 | -** This routine is not technically necessary. All thread-local storage | |
2195 | -** will be automatically deallocated once memory-management and | |
2196 | -** shared-cache are disabled and the soft heap limit has been set | |
2197 | -** to zero. This routine is provided as a convenience for users who | |
2198 | -** want to make absolutely sure they have not forgotten something | |
2199 | -** prior to killing off a thread. | |
4031 | +** Requirements: | |
4032 | +** [H16351] [H16352] [H16353] [H16354] [H16355] [H16358] | |
2200 | 4033 | */ |
2201 | -void sqlite3_thread_cleanup(void); | |
4034 | +SQLITE_API void sqlite3_soft_heap_limit(int); | |
2202 | 4035 | |
2203 | 4036 | /* |
2204 | -** CAPI3REF: Extract Metadata About A Column Of A Table | |
4037 | +** CAPI3REF: Extract Metadata About A Column Of A Table {H12850} <S60300> | |
2205 | 4038 | ** |
2206 | -** This routine | |
2207 | -** returns meta-data about a specific column of a specific database | |
2208 | -** table accessible using the connection handle passed as the first function | |
2209 | -** argument. | |
4039 | +** This routine returns metadata about a specific column of a specific | |
4040 | +** database table accessible using the [database connection] handle | |
4041 | +** passed as the first function argument. | |
2210 | 4042 | ** |
2211 | -** The column is identified by the second, third and fourth parameters to | |
4043 | +** The column is identified by the second, third and fourth parameters to | |
2212 | 4044 | ** this function. The second parameter is either the name of the database |
2213 | 4045 | ** (i.e. "main", "temp" or an attached database) containing the specified |
2214 | 4046 | ** table or NULL. If it is NULL, then all attached databases are searched |
2215 | -** for the table using the same algorithm as the database engine uses to | |
4047 | +** for the table using the same algorithm used by the database engine to | |
2216 | 4048 | ** resolve unqualified table references. |
2217 | 4049 | ** |
2218 | -** The third and fourth parameters to this function are the table and column | |
2219 | -** name of the desired column, respectively. Neither of these parameters | |
4050 | +** The third and fourth parameters to this function are the table and column | |
4051 | +** name of the desired column, respectively. Neither of these parameters | |
2220 | 4052 | ** may be NULL. |
2221 | 4053 | ** |
2222 | -** Meta information is returned by writing to the memory locations passed as | |
2223 | -** the 5th and subsequent parameters to this function. Any of these | |
2224 | -** arguments may be NULL, in which case the corresponding element of meta | |
2225 | -** information is ommitted. | |
4054 | +** Metadata is returned by writing to the memory locations passed as the 5th | |
4055 | +** and subsequent parameters to this function. Any of these arguments may be | |
4056 | +** NULL, in which case the corresponding element of metadata is omitted. | |
2226 | 4057 | ** |
2227 | -** <pre> | |
2228 | -** Parameter Output Type Description | |
2229 | -** ----------------------------------- | |
2230 | -** | |
2231 | -** 5th const char* Data type | |
2232 | -** 6th const char* Name of the default collation sequence | |
2233 | -** 7th int True if the column has a NOT NULL constraint | |
2234 | -** 8th int True if the column is part of the PRIMARY KEY | |
2235 | -** 9th int True if the column is AUTOINCREMENT | |
2236 | -** </pre> | |
4058 | +** <blockquote> | |
4059 | +** <table border="1"> | |
4060 | +** <tr><th> Parameter <th> Output<br>Type <th> Description | |
2237 | 4061 | ** |
4062 | +** <tr><td> 5th <td> const char* <td> Data type | |
4063 | +** <tr><td> 6th <td> const char* <td> Name of default collation sequence | |
4064 | +** <tr><td> 7th <td> int <td> True if column has a NOT NULL constraint | |
4065 | +** <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY | |
4066 | +** <tr><td> 9th <td> int <td> True if column is [AUTOINCREMENT] | |
4067 | +** </table> | |
4068 | +** </blockquote> | |
2238 | 4069 | ** |
2239 | -** The memory pointed to by the character pointers returned for the | |
2240 | -** declaration type and collation sequence is valid only until the next | |
2241 | -** call to any sqlite API function. | |
4070 | +** The memory pointed to by the character pointers returned for the | |
4071 | +** declaration type and collation sequence is valid only until the next | |
4072 | +** call to any SQLite API function. | |
2242 | 4073 | ** |
2243 | -** If the specified table is actually a view, then an error is returned. | |
4074 | +** If the specified table is actually a view, an [error code] is returned. | |
2244 | 4075 | ** |
2245 | -** If the specified column is "rowid", "oid" or "_rowid_" and an | |
2246 | -** INTEGER PRIMARY KEY column has been explicitly declared, then the output | |
4076 | +** If the specified column is "rowid", "oid" or "_rowid_" and an | |
4077 | +** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output | |
2247 | 4078 | ** parameters are set for the explicitly declared column. If there is no |
2248 | -** explicitly declared IPK column, then the output parameters are set as | |
2249 | -** follows: | |
4079 | +** explicitly declared [INTEGER PRIMARY KEY] column, then the output | |
4080 | +** parameters are set as follows: | |
2250 | 4081 | ** |
2251 | 4082 | ** <pre> |
2252 | 4083 | ** data type: "INTEGER" |
@@ -2258,13 +4089,13 @@ void sqlite3_thread_cleanup(void); | ||
2258 | 4089 | ** |
2259 | 4090 | ** This function may load one or more schemas from database files. If an |
2260 | 4091 | ** error occurs during this process, or if the requested table or column |
2261 | -** cannot be found, an SQLITE error code is returned and an error message | |
2262 | -** left in the database handle (to be retrieved using sqlite3_errmsg()). | |
4092 | +** cannot be found, an [error code] is returned and an error message left | |
4093 | +** in the [database connection] (to be retrieved using sqlite3_errmsg()). | |
2263 | 4094 | ** |
2264 | 4095 | ** This API is only available if the library was compiled with the |
2265 | -** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. | |
4096 | +** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined. | |
2266 | 4097 | */ |
2267 | -int sqlite3_table_column_metadata( | |
4098 | +SQLITE_API int sqlite3_table_column_metadata( | |
2268 | 4099 | sqlite3 *db, /* Connection handle */ |
2269 | 4100 | const char *zDbName, /* Database name or NULL */ |
2270 | 4101 | const char *zTableName, /* Table name */ |
@@ -2273,26 +4104,36 @@ int sqlite3_table_column_metadata( | ||
2273 | 4104 | char const **pzCollSeq, /* OUTPUT: Collation sequence name */ |
2274 | 4105 | int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ |
2275 | 4106 | int *pPrimaryKey, /* OUTPUT: True if column part of PK */ |
2276 | - int *pAutoinc /* OUTPUT: True if colums is auto-increment */ | |
4107 | + int *pAutoinc /* OUTPUT: True if column is auto-increment */ | |
2277 | 4108 | ); |
2278 | 4109 | |
2279 | 4110 | /* |
2280 | -** CAPI3REF: Load An Extension | |
4111 | +** CAPI3REF: Load An Extension {H12600} <S20500> | |
4112 | +** | |
4113 | +** This interface loads an SQLite extension library from the named file. | |
4114 | +** | |
4115 | +** {H12601} The sqlite3_load_extension() interface attempts to load an | |
4116 | +** SQLite extension library contained in the file zFile. | |
4117 | +** | |
4118 | +** {H12602} The entry point is zProc. | |
2281 | 4119 | ** |
2282 | -** Attempt to load an SQLite extension library contained in the file | |
2283 | -** zFile. The entry point is zProc. zProc may be 0 in which case the | |
2284 | -** name of the entry point defaults to "sqlite3_extension_init". | |
4120 | +** {H12603} zProc may be 0, in which case the name of the entry point | |
4121 | +** defaults to "sqlite3_extension_init". | |
2285 | 4122 | ** |
2286 | -** Return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. | |
4123 | +** {H12604} The sqlite3_load_extension() interface shall return | |
4124 | +** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. | |
2287 | 4125 | ** |
2288 | -** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with | |
2289 | -** error message text. The calling function should free this memory | |
2290 | -** by calling [sqlite3_free()]. | |
4126 | +** {H12605} If an error occurs and pzErrMsg is not 0, then the | |
4127 | +** [sqlite3_load_extension()] interface shall attempt to | |
4128 | +** fill *pzErrMsg with error message text stored in memory | |
4129 | +** obtained from [sqlite3_malloc()]. {END} The calling function | |
4130 | +** should free this memory by calling [sqlite3_free()]. | |
2291 | 4131 | ** |
2292 | -** Extension loading must be enabled using [sqlite3_enable_load_extension()] | |
2293 | -** prior to calling this API or an error will be returned. | |
4132 | +** {H12606} Extension loading must be enabled using | |
4133 | +** [sqlite3_enable_load_extension()] prior to calling this API, | |
4134 | +** otherwise an error will be returned. | |
2294 | 4135 | */ |
2295 | -int sqlite3_load_extension( | |
4136 | +SQLITE_API int sqlite3_load_extension( | |
2296 | 4137 | sqlite3 *db, /* Load the extension into this database connection */ |
2297 | 4138 | const char *zFile, /* Name of the shared library containing extension */ |
2298 | 4139 | const char *zProc, /* Entry point. Derived from zFile if 0 */ |
@@ -2300,61 +4141,63 @@ int sqlite3_load_extension( | ||
2300 | 4141 | ); |
2301 | 4142 | |
2302 | 4143 | /* |
2303 | -** CAPI3REF: Enable Or Disable Extension Loading | |
4144 | +** CAPI3REF: Enable Or Disable Extension Loading {H12620} <S20500> | |
2304 | 4145 | ** |
2305 | 4146 | ** So as not to open security holes in older applications that are |
2306 | 4147 | ** unprepared to deal with extension loading, and as a means of disabling |
2307 | -** extension loading while evaluating user-entered SQL, the following | |
2308 | -** API is provided to turn the [sqlite3_load_extension()] mechanism on and | |
2309 | -** off. It is off by default. See ticket #1863. | |
4148 | +** extension loading while evaluating user-entered SQL, the following API | |
4149 | +** is provided to turn the [sqlite3_load_extension()] mechanism on and off. | |
2310 | 4150 | ** |
2311 | -** Call this routine with onoff==1 to turn extension loading on | |
2312 | -** and call it with onoff==0 to turn it back off again. | |
4151 | +** Extension loading is off by default. See ticket #1863. | |
4152 | +** | |
4153 | +** {H12621} Call the sqlite3_enable_load_extension() routine with onoff==1 | |
4154 | +** to turn extension loading on and call it with onoff==0 to turn | |
4155 | +** it back off again. | |
4156 | +** | |
4157 | +** {H12622} Extension loading is off by default. | |
2313 | 4158 | */ |
2314 | -int sqlite3_enable_load_extension(sqlite3 *db, int onoff); | |
4159 | +SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff); | |
2315 | 4160 | |
2316 | 4161 | /* |
2317 | -** CAPI3REF: Make Arrangements To Automatically Load An Extension | |
2318 | -** | |
2319 | -** Register an extension entry point that is automatically invoked | |
2320 | -** whenever a new database connection is opened using | |
2321 | -** [sqlite3_open()] or [sqlite3_open16()]. | |
4162 | +** CAPI3REF: Automatically Load An Extensions {H12640} <S20500> | |
2322 | 4163 | ** |
2323 | 4164 | ** This API can be invoked at program startup in order to register |
2324 | 4165 | ** one or more statically linked extensions that will be available |
2325 | -** to all new database connections. | |
4166 | +** to all new [database connections]. {END} | |
2326 | 4167 | ** |
2327 | -** Duplicate extensions are detected so calling this routine multiple | |
2328 | -** times with the same extension is harmless. | |
4168 | +** This routine stores a pointer to the extension in an array that is | |
4169 | +** obtained from [sqlite3_malloc()]. If you run a memory leak checker | |
4170 | +** on your program and it reports a leak because of this array, invoke | |
4171 | +** [sqlite3_reset_auto_extension()] prior to shutdown to free the memory. | |
2329 | 4172 | ** |
2330 | -** This routine stores a pointer to the extension in an array | |
2331 | -** that is obtained from malloc(). If you run a memory leak | |
2332 | -** checker on your program and it reports a leak because of this | |
2333 | -** array, then invoke [sqlite3_automatic_extension_reset()] prior | |
2334 | -** to shutdown to free the memory. | |
4173 | +** {H12641} This function registers an extension entry point that is | |
4174 | +** automatically invoked whenever a new [database connection] | |
4175 | +** is opened using [sqlite3_open()], [sqlite3_open16()], | |
4176 | +** or [sqlite3_open_v2()]. | |
2335 | 4177 | ** |
2336 | -** Automatic extensions apply across all threads. | |
4178 | +** {H12642} Duplicate extensions are detected so calling this routine | |
4179 | +** multiple times with the same extension is harmless. | |
2337 | 4180 | ** |
2338 | -** This interface is experimental and is subject to change or | |
2339 | -** removal in future releases of SQLite. | |
4181 | +** {H12643} This routine stores a pointer to the extension in an array | |
4182 | +** that is obtained from [sqlite3_malloc()]. | |
4183 | +** | |
4184 | +** {H12644} Automatic extensions apply across all threads. | |
2340 | 4185 | */ |
2341 | -int sqlite3_auto_extension(void *xEntryPoint); | |
2342 | - | |
4186 | +SQLITE_API int sqlite3_auto_extension(void (*xEntryPoint)(void)); | |
2343 | 4187 | |
2344 | 4188 | /* |
2345 | -** CAPI3REF: Reset Automatic Extension Loading | |
4189 | +** CAPI3REF: Reset Automatic Extension Loading {H12660} <S20500> | |
2346 | 4190 | ** |
2347 | -** Disable all previously registered automatic extensions. This | |
2348 | -** routine undoes the effect of all prior [sqlite3_automatic_extension()] | |
2349 | -** calls. | |
4191 | +** This function disables all previously registered automatic | |
4192 | +** extensions. {END} It undoes the effect of all prior | |
4193 | +** [sqlite3_auto_extension()] calls. | |
2350 | 4194 | ** |
2351 | -** This call disabled automatic extensions in all threads. | |
4195 | +** {H12661} This function disables all previously registered | |
4196 | +** automatic extensions. | |
2352 | 4197 | ** |
2353 | -** This interface is experimental and is subject to change or | |
2354 | -** removal in future releases of SQLite. | |
4198 | +** {H12662} This function disables automatic extensions in all threads. | |
2355 | 4199 | */ |
2356 | -void sqlite3_reset_auto_extension(void); | |
2357 | - | |
4200 | +SQLITE_API void sqlite3_reset_auto_extension(void); | |
2358 | 4201 | |
2359 | 4202 | /* |
2360 | 4203 | ****** EXPERIMENTAL - subject to change without notice ************** |
@@ -2363,7 +4206,7 @@ void sqlite3_reset_auto_extension(void); | ||
2363 | 4206 | ** to be experimental. The interface might change in incompatible ways. |
2364 | 4207 | ** If this is a problem for you, do not use the interface at this time. |
2365 | 4208 | ** |
2366 | -** When the virtual-table mechanism stablizes, we will declare the | |
4209 | +** When the virtual-table mechanism stabilizes, we will declare the | |
2367 | 4210 | ** interface fixed, support it indefinitely, and remove this comment. |
2368 | 4211 | */ |
2369 | 4212 |
@@ -2376,9 +4219,21 @@ typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; | ||
2376 | 4219 | typedef struct sqlite3_module sqlite3_module; |
2377 | 4220 | |
2378 | 4221 | /* |
2379 | -** A module is a class of virtual tables. Each module is defined | |
2380 | -** by an instance of the following structure. This structure consists | |
2381 | -** mostly of methods for the module. | |
4222 | +** CAPI3REF: Virtual Table Object {H18000} <S20400> | |
4223 | +** KEYWORDS: sqlite3_module {virtual table module} | |
4224 | +** EXPERIMENTAL | |
4225 | +** | |
4226 | +** This structure, sometimes called a a "virtual table module", | |
4227 | +** defines the implementation of a [virtual tables]. | |
4228 | +** This structure consists mostly of methods for the module. | |
4229 | +** | |
4230 | +** A virtual table module is created by filling in a persistent | |
4231 | +** instance of this structure and passing a pointer to that instance | |
4232 | +** to [sqlite3_create_module()] or [sqlite3_create_module_v2()]. | |
4233 | +** The registration remains valid until it is replaced by a different | |
4234 | +** module or until the [database connection] closes. The content | |
4235 | +** of this structure must not change while it is registered with | |
4236 | +** any database connection. | |
2382 | 4237 | */ |
2383 | 4238 | struct sqlite3_module { |
2384 | 4239 | int iVersion; |
@@ -2398,8 +4253,8 @@ struct sqlite3_module { | ||
2398 | 4253 | int (*xNext)(sqlite3_vtab_cursor*); |
2399 | 4254 | int (*xEof)(sqlite3_vtab_cursor*); |
2400 | 4255 | int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int); |
2401 | - int (*xRowid)(sqlite3_vtab_cursor*, sqlite_int64 *pRowid); | |
2402 | - int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite_int64 *); | |
4256 | + int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid); | |
4257 | + int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *); | |
2403 | 4258 | int (*xBegin)(sqlite3_vtab *pVTab); |
2404 | 4259 | int (*xSync)(sqlite3_vtab *pVTab); |
2405 | 4260 | int (*xCommit)(sqlite3_vtab *pVTab); |
@@ -2407,30 +4262,32 @@ struct sqlite3_module { | ||
2407 | 4262 | int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, |
2408 | 4263 | void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), |
2409 | 4264 | void **ppArg); |
2410 | - | |
2411 | 4265 | int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); |
2412 | 4266 | }; |
2413 | 4267 | |
2414 | 4268 | /* |
4269 | +** CAPI3REF: Virtual Table Indexing Information {H18100} <S20400> | |
4270 | +** KEYWORDS: sqlite3_index_info | |
4271 | +** EXPERIMENTAL | |
4272 | +** | |
2415 | 4273 | ** The sqlite3_index_info structure and its substructures is used to |
2416 | -** pass information into and receive the reply from the xBestIndex | |
2417 | -** method of an sqlite3_module. The fields under **Inputs** are the | |
4274 | +** pass information into and receive the reply from the [xBestIndex] | |
4275 | +** method of a [virtual table module]. The fields under **Inputs** are the | |
2418 | 4276 | ** inputs to xBestIndex and are read-only. xBestIndex inserts its |
2419 | 4277 | ** results into the **Outputs** fields. |
2420 | 4278 | ** |
2421 | -** The aConstraint[] array records WHERE clause constraints of the | |
2422 | -** form: | |
4279 | +** The aConstraint[] array records WHERE clause constraints of the form: | |
2423 | 4280 | ** |
2424 | -** column OP expr | |
4281 | +** <pre>column OP expr</pre> | |
2425 | 4282 | ** |
2426 | -** Where OP is =, <, <=, >, or >=. The particular operator is stored | |
2427 | -** in aConstraint[].op. The index of the column is stored in | |
4283 | +** where OP is =, <, <=, >, or >=. The particular operator is | |
4284 | +** stored in aConstraint[].op. The index of the column is stored in | |
2428 | 4285 | ** aConstraint[].iColumn. aConstraint[].usable is TRUE if the |
2429 | 4286 | ** expr on the right-hand side can be evaluated (and thus the constraint |
2430 | 4287 | ** is usable) and false if it cannot. |
2431 | 4288 | ** |
2432 | 4289 | ** The optimizer automatically inverts terms of the form "expr OP column" |
2433 | -** and makes other simplificatinos to the WHERE clause in an attempt to | |
4290 | +** and makes other simplifications to the WHERE clause in an attempt to | |
2434 | 4291 | ** get as many WHERE clause terms into the form shown above as possible. |
2435 | 4292 | ** The aConstraint[] array only reports WHERE clause terms in the correct |
2436 | 4293 | ** form that refer to the particular virtual table being queried. |
@@ -2438,17 +4295,19 @@ struct sqlite3_module { | ||
2438 | 4295 | ** Information about the ORDER BY clause is stored in aOrderBy[]. |
2439 | 4296 | ** Each term of aOrderBy records a column of the ORDER BY clause. |
2440 | 4297 | ** |
2441 | -** The xBestIndex method must fill aConstraintUsage[] with information | |
4298 | +** The [xBestIndex] method must fill aConstraintUsage[] with information | |
2442 | 4299 | ** about what parameters to pass to xFilter. If argvIndex>0 then |
2443 | 4300 | ** the right-hand side of the corresponding aConstraint[] is evaluated |
2444 | 4301 | ** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit |
2445 | 4302 | ** is true, then the constraint is assumed to be fully handled by the |
2446 | 4303 | ** virtual table and is not checked again by SQLite. |
2447 | 4304 | ** |
2448 | -** The idxNum and idxPtr values are recorded and passed into xFilter. | |
2449 | -** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true. | |
4305 | +** The idxNum and idxPtr values are recorded and passed into the | |
4306 | +** [xFilter] method. | |
4307 | +** [sqlite3_free()] is used to free idxPtr if and only iff | |
4308 | +** needToFreeIdxPtr is true. | |
2450 | 4309 | ** |
2451 | -** The orderByConsumed means that output from xFilter will occur in | |
4310 | +** The orderByConsumed means that output from [xFilter]/[xNext] will occur in | |
2452 | 4311 | ** the correct order to satisfy the ORDER BY clause so that no separate |
2453 | 4312 | ** sorting step is required. |
2454 | 4313 | ** |
@@ -2459,24 +4318,23 @@ struct sqlite3_module { | ||
2459 | 4318 | */ |
2460 | 4319 | struct sqlite3_index_info { |
2461 | 4320 | /* Inputs */ |
2462 | - const int nConstraint; /* Number of entries in aConstraint */ | |
2463 | - const struct sqlite3_index_constraint { | |
4321 | + int nConstraint; /* Number of entries in aConstraint */ | |
4322 | + struct sqlite3_index_constraint { | |
2464 | 4323 | int iColumn; /* Column on left-hand side of constraint */ |
2465 | 4324 | unsigned char op; /* Constraint operator */ |
2466 | 4325 | unsigned char usable; /* True if this constraint is usable */ |
2467 | 4326 | int iTermOffset; /* Used internally - xBestIndex should ignore */ |
2468 | - } *const aConstraint; /* Table of WHERE clause constraints */ | |
2469 | - const int nOrderBy; /* Number of terms in the ORDER BY clause */ | |
2470 | - const struct sqlite3_index_orderby { | |
4327 | + } *aConstraint; /* Table of WHERE clause constraints */ | |
4328 | + int nOrderBy; /* Number of terms in the ORDER BY clause */ | |
4329 | + struct sqlite3_index_orderby { | |
2471 | 4330 | int iColumn; /* Column number */ |
2472 | 4331 | unsigned char desc; /* True for DESC. False for ASC. */ |
2473 | - } *const aOrderBy; /* The ORDER BY clause */ | |
2474 | - | |
4332 | + } *aOrderBy; /* The ORDER BY clause */ | |
2475 | 4333 | /* Outputs */ |
2476 | 4334 | struct sqlite3_index_constraint_usage { |
2477 | 4335 | int argvIndex; /* if >0, constraint is part of argv to xFilter */ |
2478 | 4336 | unsigned char omit; /* Do not code a test for this constraint */ |
2479 | - } *const aConstraintUsage; | |
4337 | + } *aConstraintUsage; | |
2480 | 4338 | int idxNum; /* Number used to identify the index */ |
2481 | 4339 | char *idxStr; /* String, possibly obtained from sqlite3_malloc */ |
2482 | 4340 | int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ |
@@ -2491,59 +4349,89 @@ struct sqlite3_index_info { | ||
2491 | 4349 | #define SQLITE_INDEX_CONSTRAINT_MATCH 64 |
2492 | 4350 | |
2493 | 4351 | /* |
2494 | -** This routine is used to register a new module name with an SQLite | |
2495 | -** connection. Module names must be registered before creating new | |
2496 | -** virtual tables on the module, or before using preexisting virtual | |
2497 | -** tables of the module. | |
4352 | +** CAPI3REF: Register A Virtual Table Implementation {H18200} <S20400> | |
4353 | +** EXPERIMENTAL | |
4354 | +** | |
4355 | +** This routine is used to register a new [virtual table module] name. | |
4356 | +** Module names must be registered before | |
4357 | +** creating a new [virtual table] using the module, or before using a | |
4358 | +** preexisting [virtual table] for the module. | |
4359 | +** | |
4360 | +** The module name is registered on the [database connection] specified | |
4361 | +** by the first parameter. The name of the module is given by the | |
4362 | +** second parameter. The third parameter is a pointer to | |
4363 | +** the implementation of the [virtual table module]. The fourth | |
4364 | +** parameter is an arbitrary client data pointer that is passed through | |
4365 | +** into the [xCreate] and [xConnect] methods of the virtual table module | |
4366 | +** when a new virtual table is be being created or reinitialized. | |
4367 | +** | |
4368 | +** This interface has exactly the same effect as calling | |
4369 | +** [sqlite3_create_module_v2()] with a NULL client data destructor. | |
2498 | 4370 | */ |
2499 | -int sqlite3_create_module( | |
4371 | +SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_create_module( | |
2500 | 4372 | sqlite3 *db, /* SQLite connection to register module with */ |
2501 | 4373 | const char *zName, /* Name of the module */ |
2502 | - const sqlite3_module *, /* Methods for the module */ | |
2503 | - void * /* Client data for xCreate/xConnect */ | |
4374 | + const sqlite3_module *p, /* Methods for the module */ | |
4375 | + void *pClientData /* Client data for xCreate/xConnect */ | |
2504 | 4376 | ); |
2505 | 4377 | |
2506 | 4378 | /* |
2507 | -** This routine is identical to the sqlite3_create_module() method above, | |
2508 | -** except that it allows a destructor function to be specified. It is | |
2509 | -** even more experimental than the rest of the virtual tables API. | |
4379 | +** CAPI3REF: Register A Virtual Table Implementation {H18210} <S20400> | |
4380 | +** EXPERIMENTAL | |
4381 | +** | |
4382 | +** This routine is identical to the [sqlite3_create_module()] method, | |
4383 | +** except that it has an extra parameter to specify | |
4384 | +** a destructor function for the client data pointer. SQLite will | |
4385 | +** invoke the destructor function (if it is not NULL) when SQLite | |
4386 | +** no longer needs the pClientData pointer. | |
2510 | 4387 | */ |
2511 | -int sqlite3_create_module_v2( | |
4388 | +SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_create_module_v2( | |
2512 | 4389 | sqlite3 *db, /* SQLite connection to register module with */ |
2513 | 4390 | const char *zName, /* Name of the module */ |
2514 | - const sqlite3_module *, /* Methods for the module */ | |
2515 | - void *, /* Client data for xCreate/xConnect */ | |
4391 | + const sqlite3_module *p, /* Methods for the module */ | |
4392 | + void *pClientData, /* Client data for xCreate/xConnect */ | |
2516 | 4393 | void(*xDestroy)(void*) /* Module destructor function */ |
2517 | 4394 | ); |
2518 | 4395 | |
2519 | 4396 | /* |
2520 | -** Every module implementation uses a subclass of the following structure | |
2521 | -** to describe a particular instance of the module. Each subclass will | |
2522 | -** be taylored to the specific needs of the module implementation. The | |
2523 | -** purpose of this superclass is to define certain fields that are common | |
2524 | -** to all module implementations. | |
4397 | +** CAPI3REF: Virtual Table Instance Object {H18010} <S20400> | |
4398 | +** KEYWORDS: sqlite3_vtab | |
4399 | +** EXPERIMENTAL | |
4400 | +** | |
4401 | +** Every [virtual table module] implementation uses a subclass | |
4402 | +** of the following structure to describe a particular instance | |
4403 | +** of the [virtual table]. Each subclass will | |
4404 | +** be tailored to the specific needs of the module implementation. | |
4405 | +** The purpose of this superclass is to define certain fields that are | |
4406 | +** common to all module implementations. | |
2525 | 4407 | ** |
2526 | 4408 | ** Virtual tables methods can set an error message by assigning a |
2527 | -** string obtained from sqlite3_mprintf() to zErrMsg. The method should | |
2528 | -** take care that any prior string is freed by a call to sqlite3_free() | |
4409 | +** string obtained from [sqlite3_mprintf()] to zErrMsg. The method should | |
4410 | +** take care that any prior string is freed by a call to [sqlite3_free()] | |
2529 | 4411 | ** prior to assigning a new string to zErrMsg. After the error message |
2530 | 4412 | ** is delivered up to the client application, the string will be automatically |
2531 | -** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note | |
2532 | -** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field | |
2533 | -** since virtual tables are commonly implemented in loadable extensions which | |
2534 | -** do not have access to sqlite3MPrintf() or sqlite3Free(). | |
4413 | +** freed by sqlite3_free() and the zErrMsg field will be zeroed. | |
2535 | 4414 | */ |
2536 | 4415 | struct sqlite3_vtab { |
2537 | 4416 | const sqlite3_module *pModule; /* The module for this virtual table */ |
2538 | - int nRef; /* Used internally */ | |
4417 | + int nRef; /* NO LONGER USED */ | |
2539 | 4418 | char *zErrMsg; /* Error message from sqlite3_mprintf() */ |
2540 | 4419 | /* Virtual table implementations will typically add additional fields */ |
2541 | 4420 | }; |
2542 | 4421 | |
2543 | -/* Every module implementation uses a subclass of the following structure | |
2544 | -** to describe cursors that point into the virtual table and are used | |
4422 | +/* | |
4423 | +** CAPI3REF: Virtual Table Cursor Object {H18020} <S20400> | |
4424 | +** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor} | |
4425 | +** EXPERIMENTAL | |
4426 | +** | |
4427 | +** Every [virtual table module] implementation uses a subclass of the | |
4428 | +** following structure to describe cursors that point into the | |
4429 | +** [virtual table] and are used | |
2545 | 4430 | ** to loop through the virtual table. Cursors are created using the |
2546 | -** xOpen method of the module. Each module implementation will define | |
4431 | +** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed | |
4432 | +** by the [sqlite3_module.xClose | xClose] method. Cussors are used | |
4433 | +** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods | |
4434 | +** of the module. Each module implementation will define | |
2547 | 4435 | ** the content of a cursor structure to suit its own needs. |
2548 | 4436 | ** |
2549 | 4437 | ** This superclass exists in order to define fields of the cursor that |
@@ -2555,15 +4443,23 @@ struct sqlite3_vtab_cursor { | ||
2555 | 4443 | }; |
2556 | 4444 | |
2557 | 4445 | /* |
2558 | -** The xCreate and xConnect methods of a module use the following API | |
4446 | +** CAPI3REF: Declare The Schema Of A Virtual Table {H18280} <S20400> | |
4447 | +** EXPERIMENTAL | |
4448 | +** | |
4449 | +** The [xCreate] and [xConnect] methods of a | |
4450 | +** [virtual table module] call this interface | |
2559 | 4451 | ** to declare the format (the names and datatypes of the columns) of |
2560 | 4452 | ** the virtual tables they implement. |
2561 | 4453 | */ |
2562 | -int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); | |
4454 | +SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_declare_vtab(sqlite3*, const char *zSQL); | |
2563 | 4455 | |
2564 | 4456 | /* |
4457 | +** CAPI3REF: Overload A Function For A Virtual Table {H18300} <S20400> | |
4458 | +** EXPERIMENTAL | |
4459 | +** | |
2565 | 4460 | ** Virtual tables can provide alternative implementations of functions |
2566 | -** using the xFindFunction method. But global versions of those functions | |
4461 | +** using the [xFindFunction] method of the [virtual table module]. | |
4462 | +** But global versions of those functions | |
2567 | 4463 | ** must exist in order to be overloaded. |
2568 | 4464 | ** |
2569 | 4465 | ** This API makes sure a global version of a function with a particular |
@@ -2571,13 +4467,10 @@ int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); | ||
2571 | 4467 | ** before this API is called, a new function is created. The implementation |
2572 | 4468 | ** of the new function always causes an exception to be thrown. So |
2573 | 4469 | ** the new function is not good for anything by itself. Its only |
2574 | -** purpose is to be a place-holder function that can be overloaded | |
2575 | -** by virtual tables. | |
2576 | -** | |
2577 | -** This API should be considered part of the virtual table interface, | |
2578 | -** which is experimental and subject to change. | |
4470 | +** purpose is to be a placeholder function that can be overloaded | |
4471 | +** by a [virtual table]. | |
2579 | 4472 | */ |
2580 | -int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); | |
4473 | +SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); | |
2581 | 4474 | |
2582 | 4475 | /* |
2583 | 4476 | ** The interface to the virtual-table mechanism defined above (back up |
@@ -2585,108 +4478,1271 @@ int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); | ||
2585 | 4478 | ** to be experimental. The interface might change in incompatible ways. |
2586 | 4479 | ** If this is a problem for you, do not use the interface at this time. |
2587 | 4480 | ** |
2588 | -** When the virtual-table mechanism stablizes, we will declare the | |
4481 | +** When the virtual-table mechanism stabilizes, we will declare the | |
2589 | 4482 | ** interface fixed, support it indefinitely, and remove this comment. |
2590 | 4483 | ** |
2591 | 4484 | ****** EXPERIMENTAL - subject to change without notice ************** |
2592 | 4485 | */ |
2593 | 4486 | |
2594 | 4487 | /* |
2595 | -** CAPI3REF: A Handle To An Open BLOB | |
4488 | +** CAPI3REF: A Handle To An Open BLOB {H17800} <S30230> | |
4489 | +** KEYWORDS: {BLOB handle} {BLOB handles} | |
2596 | 4490 | ** |
2597 | -** An instance of the following opaque structure is used to | |
2598 | -** represent an blob-handle. A blob-handle is created by | |
2599 | -** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()]. | |
4491 | +** An instance of this object represents an open BLOB on which | |
4492 | +** [sqlite3_blob_open | incremental BLOB I/O] can be performed. | |
4493 | +** Objects of this type are created by [sqlite3_blob_open()] | |
4494 | +** and destroyed by [sqlite3_blob_close()]. | |
2600 | 4495 | ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces |
2601 | -** can be used to read or write small subsections of the blob. | |
2602 | -** The [sqltie3_blob_size()] interface returns the size of the | |
2603 | -** blob in bytes. | |
4496 | +** can be used to read or write small subsections of the BLOB. | |
4497 | +** The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes. | |
2604 | 4498 | */ |
2605 | 4499 | typedef struct sqlite3_blob sqlite3_blob; |
2606 | 4500 | |
2607 | 4501 | /* |
2608 | -** CAPI3REF: Open A BLOB For Incremental I/O | |
4502 | +** CAPI3REF: Open A BLOB For Incremental I/O {H17810} <S30230> | |
2609 | 4503 | ** |
2610 | -** Open a handle to the blob located in row iRow,, column zColumn, | |
2611 | -** table zTable in database zDb. i.e. the same blob that would | |
2612 | -** be selected by: | |
4504 | +** This interfaces opens a [BLOB handle | handle] to the BLOB located | |
4505 | +** in row iRow, column zColumn, table zTable in database zDb; | |
4506 | +** in other words, the same BLOB that would be selected by: | |
2613 | 4507 | ** |
2614 | 4508 | ** <pre> |
2615 | -** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow; | |
2616 | -** </pre> | |
2617 | -** | |
2618 | -** If the flags parameter is non-zero, the blob is opened for | |
2619 | -** read and write access. If it is zero, the blob is opened for read | |
2620 | -** access. | |
2621 | -** | |
2622 | -** On success, [SQLITE_OK] is returned and the new | |
2623 | -** [sqlite3_blob | blob handle] is written to *ppBlob. | |
2624 | -** Otherwise an error code is returned and | |
2625 | -** any value written to *ppBlob should not be used by the caller. | |
2626 | -** This function sets the database-handle error code and message | |
2627 | -** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()]. | |
4509 | +** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow; | |
4510 | +** </pre> {END} | |
4511 | +** | |
4512 | +** If the flags parameter is non-zero, then the BLOB is opened for read | |
4513 | +** and write access. If it is zero, the BLOB is opened for read access. | |
4514 | +** | |
4515 | +** Note that the database name is not the filename that contains | |
4516 | +** the database but rather the symbolic name of the database that | |
4517 | +** is assigned when the database is connected using [ATTACH]. | |
4518 | +** For the main database file, the database name is "main". | |
4519 | +** For TEMP tables, the database name is "temp". | |
4520 | +** | |
4521 | +** On success, [SQLITE_OK] is returned and the new [BLOB handle] is written | |
4522 | +** to *ppBlob. Otherwise an [error code] is returned and *ppBlob is set | |
4523 | +** to be a null pointer. | |
4524 | +** This function sets the [database connection] error code and message | |
4525 | +** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()] and related | |
4526 | +** functions. Note that the *ppBlob variable is always initialized in a | |
4527 | +** way that makes it safe to invoke [sqlite3_blob_close()] on *ppBlob | |
4528 | +** regardless of the success or failure of this routine. | |
4529 | +** | |
4530 | +** If the row that a BLOB handle points to is modified by an | |
4531 | +** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects | |
4532 | +** then the BLOB handle is marked as "expired". | |
4533 | +** This is true if any column of the row is changed, even a column | |
4534 | +** other than the one the BLOB handle is open on. | |
4535 | +** Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for | |
4536 | +** a expired BLOB handle fail with an return code of [SQLITE_ABORT]. | |
4537 | +** Changes written into a BLOB prior to the BLOB expiring are not | |
4538 | +** rollback by the expiration of the BLOB. Such changes will eventually | |
4539 | +** commit if the transaction continues to completion. | |
4540 | +** | |
4541 | +** Use the [sqlite3_blob_bytes()] interface to determine the size of | |
4542 | +** the opened blob. The size of a blob may not be changed by this | |
4543 | +** interface. Use the [UPDATE] SQL command to change the size of a | |
4544 | +** blob. | |
4545 | +** | |
4546 | +** The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces | |
4547 | +** and the built-in [zeroblob] SQL function can be used, if desired, | |
4548 | +** to create an empty, zero-filled blob in which to read or write using | |
4549 | +** this interface. | |
4550 | +** | |
4551 | +** To avoid a resource leak, every open [BLOB handle] should eventually | |
4552 | +** be released by a call to [sqlite3_blob_close()]. | |
4553 | +** | |
4554 | +** Requirements: | |
4555 | +** [H17813] [H17814] [H17816] [H17819] [H17821] [H17824] | |
2628 | 4556 | */ |
2629 | -int sqlite3_blob_open( | |
4557 | +SQLITE_API int sqlite3_blob_open( | |
2630 | 4558 | sqlite3*, |
2631 | 4559 | const char *zDb, |
2632 | 4560 | const char *zTable, |
2633 | 4561 | const char *zColumn, |
2634 | - sqlite_int64 iRow, | |
4562 | + sqlite3_int64 iRow, | |
2635 | 4563 | int flags, |
2636 | 4564 | sqlite3_blob **ppBlob |
2637 | 4565 | ); |
2638 | 4566 | |
2639 | 4567 | /* |
2640 | -** CAPI3REF: Close A BLOB Handle | |
4568 | +** CAPI3REF: Close A BLOB Handle {H17830} <S30230> | |
4569 | +** | |
4570 | +** Closes an open [BLOB handle]. | |
4571 | +** | |
4572 | +** Closing a BLOB shall cause the current transaction to commit | |
4573 | +** if there are no other BLOBs, no pending prepared statements, and the | |
4574 | +** database connection is in [autocommit mode]. | |
4575 | +** If any writes were made to the BLOB, they might be held in cache | |
4576 | +** until the close operation if they will fit. | |
4577 | +** | |
4578 | +** Closing the BLOB often forces the changes | |
4579 | +** out to disk and so if any I/O errors occur, they will likely occur | |
4580 | +** at the time when the BLOB is closed. Any errors that occur during | |
4581 | +** closing are reported as a non-zero return value. | |
4582 | +** | |
4583 | +** The BLOB is closed unconditionally. Even if this routine returns | |
4584 | +** an error code, the BLOB is still closed. | |
4585 | +** | |
4586 | +** Calling this routine with a null pointer (which as would be returned | |
4587 | +** by failed call to [sqlite3_blob_open()]) is a harmless no-op. | |
4588 | +** | |
4589 | +** Requirements: | |
4590 | +** [H17833] [H17836] [H17839] | |
4591 | +*/ | |
4592 | +SQLITE_API int sqlite3_blob_close(sqlite3_blob *); | |
4593 | + | |
4594 | +/* | |
4595 | +** CAPI3REF: Return The Size Of An Open BLOB {H17840} <S30230> | |
4596 | +** | |
4597 | +** Returns the size in bytes of the BLOB accessible via the | |
4598 | +** successfully opened [BLOB handle] in its only argument. The | |
4599 | +** incremental blob I/O routines can only read or overwriting existing | |
4600 | +** blob content; they cannot change the size of a blob. | |
4601 | +** | |
4602 | +** This routine only works on a [BLOB handle] which has been created | |
4603 | +** by a prior successful call to [sqlite3_blob_open()] and which has not | |
4604 | +** been closed by [sqlite3_blob_close()]. Passing any other pointer in | |
4605 | +** to this routine results in undefined and probably undesirable behavior. | |
4606 | +** | |
4607 | +** Requirements: | |
4608 | +** [H17843] | |
4609 | +*/ | |
4610 | +SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *); | |
4611 | + | |
4612 | +/* | |
4613 | +** CAPI3REF: Read Data From A BLOB Incrementally {H17850} <S30230> | |
4614 | +** | |
4615 | +** This function is used to read data from an open [BLOB handle] into a | |
4616 | +** caller-supplied buffer. N bytes of data are copied into buffer Z | |
4617 | +** from the open BLOB, starting at offset iOffset. | |
4618 | +** | |
4619 | +** If offset iOffset is less than N bytes from the end of the BLOB, | |
4620 | +** [SQLITE_ERROR] is returned and no data is read. If N or iOffset is | |
4621 | +** less than zero, [SQLITE_ERROR] is returned and no data is read. | |
4622 | +** The size of the blob (and hence the maximum value of N+iOffset) | |
4623 | +** can be determined using the [sqlite3_blob_bytes()] interface. | |
4624 | +** | |
4625 | +** An attempt to read from an expired [BLOB handle] fails with an | |
4626 | +** error code of [SQLITE_ABORT]. | |
4627 | +** | |
4628 | +** On success, SQLITE_OK is returned. | |
4629 | +** Otherwise, an [error code] or an [extended error code] is returned. | |
4630 | +** | |
4631 | +** This routine only works on a [BLOB handle] which has been created | |
4632 | +** by a prior successful call to [sqlite3_blob_open()] and which has not | |
4633 | +** been closed by [sqlite3_blob_close()]. Passing any other pointer in | |
4634 | +** to this routine results in undefined and probably undesirable behavior. | |
4635 | +** | |
4636 | +** See also: [sqlite3_blob_write()]. | |
4637 | +** | |
4638 | +** Requirements: | |
4639 | +** [H17853] [H17856] [H17859] [H17862] [H17863] [H17865] [H17868] | |
4640 | +*/ | |
4641 | +SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); | |
4642 | + | |
4643 | +/* | |
4644 | +** CAPI3REF: Write Data Into A BLOB Incrementally {H17870} <S30230> | |
4645 | +** | |
4646 | +** This function is used to write data into an open [BLOB handle] from a | |
4647 | +** caller-supplied buffer. N bytes of data are copied from the buffer Z | |
4648 | +** into the open BLOB, starting at offset iOffset. | |
4649 | +** | |
4650 | +** If the [BLOB handle] passed as the first argument was not opened for | |
4651 | +** writing (the flags parameter to [sqlite3_blob_open()] was zero), | |
4652 | +** this function returns [SQLITE_READONLY]. | |
4653 | +** | |
4654 | +** This function may only modify the contents of the BLOB; it is | |
4655 | +** not possible to increase the size of a BLOB using this API. | |
4656 | +** If offset iOffset is less than N bytes from the end of the BLOB, | |
4657 | +** [SQLITE_ERROR] is returned and no data is written. If N is | |
4658 | +** less than zero [SQLITE_ERROR] is returned and no data is written. | |
4659 | +** The size of the BLOB (and hence the maximum value of N+iOffset) | |
4660 | +** can be determined using the [sqlite3_blob_bytes()] interface. | |
4661 | +** | |
4662 | +** An attempt to write to an expired [BLOB handle] fails with an | |
4663 | +** error code of [SQLITE_ABORT]. Writes to the BLOB that occurred | |
4664 | +** before the [BLOB handle] expired are not rolled back by the | |
4665 | +** expiration of the handle, though of course those changes might | |
4666 | +** have been overwritten by the statement that expired the BLOB handle | |
4667 | +** or by other independent statements. | |
4668 | +** | |
4669 | +** On success, SQLITE_OK is returned. | |
4670 | +** Otherwise, an [error code] or an [extended error code] is returned. | |
4671 | +** | |
4672 | +** This routine only works on a [BLOB handle] which has been created | |
4673 | +** by a prior successful call to [sqlite3_blob_open()] and which has not | |
4674 | +** been closed by [sqlite3_blob_close()]. Passing any other pointer in | |
4675 | +** to this routine results in undefined and probably undesirable behavior. | |
4676 | +** | |
4677 | +** See also: [sqlite3_blob_read()]. | |
4678 | +** | |
4679 | +** Requirements: | |
4680 | +** [H17873] [H17874] [H17875] [H17876] [H17877] [H17879] [H17882] [H17885] | |
4681 | +** [H17888] | |
4682 | +*/ | |
4683 | +SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); | |
4684 | + | |
4685 | +/* | |
4686 | +** CAPI3REF: Virtual File System Objects {H11200} <S20100> | |
4687 | +** | |
4688 | +** A virtual filesystem (VFS) is an [sqlite3_vfs] object | |
4689 | +** that SQLite uses to interact | |
4690 | +** with the underlying operating system. Most SQLite builds come with a | |
4691 | +** single default VFS that is appropriate for the host computer. | |
4692 | +** New VFSes can be registered and existing VFSes can be unregistered. | |
4693 | +** The following interfaces are provided. | |
4694 | +** | |
4695 | +** The sqlite3_vfs_find() interface returns a pointer to a VFS given its name. | |
4696 | +** Names are case sensitive. | |
4697 | +** Names are zero-terminated UTF-8 strings. | |
4698 | +** If there is no match, a NULL pointer is returned. | |
4699 | +** If zVfsName is NULL then the default VFS is returned. | |
4700 | +** | |
4701 | +** New VFSes are registered with sqlite3_vfs_register(). | |
4702 | +** Each new VFS becomes the default VFS if the makeDflt flag is set. | |
4703 | +** The same VFS can be registered multiple times without injury. | |
4704 | +** To make an existing VFS into the default VFS, register it again | |
4705 | +** with the makeDflt flag set. If two different VFSes with the | |
4706 | +** same name are registered, the behavior is undefined. If a | |
4707 | +** VFS is registered with a name that is NULL or an empty string, | |
4708 | +** then the behavior is undefined. | |
4709 | +** | |
4710 | +** Unregister a VFS with the sqlite3_vfs_unregister() interface. | |
4711 | +** If the default VFS is unregistered, another VFS is chosen as | |
4712 | +** the default. The choice for the new VFS is arbitrary. | |
4713 | +** | |
4714 | +** Requirements: | |
4715 | +** [H11203] [H11206] [H11209] [H11212] [H11215] [H11218] | |
4716 | +*/ | |
4717 | +SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); | |
4718 | +SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); | |
4719 | +SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*); | |
4720 | + | |
4721 | +/* | |
4722 | +** CAPI3REF: Mutexes {H17000} <S20000> | |
4723 | +** | |
4724 | +** The SQLite core uses these routines for thread | |
4725 | +** synchronization. Though they are intended for internal | |
4726 | +** use by SQLite, code that links against SQLite is | |
4727 | +** permitted to use any of these routines. | |
4728 | +** | |
4729 | +** The SQLite source code contains multiple implementations | |
4730 | +** of these mutex routines. An appropriate implementation | |
4731 | +** is selected automatically at compile-time. The following | |
4732 | +** implementations are available in the SQLite core: | |
4733 | +** | |
4734 | +** <ul> | |
4735 | +** <li> SQLITE_MUTEX_OS2 | |
4736 | +** <li> SQLITE_MUTEX_PTHREAD | |
4737 | +** <li> SQLITE_MUTEX_W32 | |
4738 | +** <li> SQLITE_MUTEX_NOOP | |
4739 | +** </ul> | |
2641 | 4740 | ** |
2642 | -** Close an open [sqlite3_blob | blob handle]. | |
4741 | +** The SQLITE_MUTEX_NOOP implementation is a set of routines | |
4742 | +** that does no real locking and is appropriate for use in | |
4743 | +** a single-threaded application. The SQLITE_MUTEX_OS2, | |
4744 | +** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations | |
4745 | +** are appropriate for use on OS/2, Unix, and Windows. | |
4746 | +** | |
4747 | +** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor | |
4748 | +** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex | |
4749 | +** implementation is included with the library. In this case the | |
4750 | +** application must supply a custom mutex implementation using the | |
4751 | +** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function | |
4752 | +** before calling sqlite3_initialize() or any other public sqlite3_ | |
4753 | +** function that calls sqlite3_initialize(). | |
4754 | +** | |
4755 | +** {H17011} The sqlite3_mutex_alloc() routine allocates a new | |
4756 | +** mutex and returns a pointer to it. {H17012} If it returns NULL | |
4757 | +** that means that a mutex could not be allocated. {H17013} SQLite | |
4758 | +** will unwind its stack and return an error. {H17014} The argument | |
4759 | +** to sqlite3_mutex_alloc() is one of these integer constants: | |
4760 | +** | |
4761 | +** <ul> | |
4762 | +** <li> SQLITE_MUTEX_FAST | |
4763 | +** <li> SQLITE_MUTEX_RECURSIVE | |
4764 | +** <li> SQLITE_MUTEX_STATIC_MASTER | |
4765 | +** <li> SQLITE_MUTEX_STATIC_MEM | |
4766 | +** <li> SQLITE_MUTEX_STATIC_MEM2 | |
4767 | +** <li> SQLITE_MUTEX_STATIC_PRNG | |
4768 | +** <li> SQLITE_MUTEX_STATIC_LRU | |
4769 | +** <li> SQLITE_MUTEX_STATIC_LRU2 | |
4770 | +** </ul> | |
4771 | +** | |
4772 | +** {H17015} The first two constants cause sqlite3_mutex_alloc() to create | |
4773 | +** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE | |
4774 | +** is used but not necessarily so when SQLITE_MUTEX_FAST is used. {END} | |
4775 | +** The mutex implementation does not need to make a distinction | |
4776 | +** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does | |
4777 | +** not want to. {H17016} But SQLite will only request a recursive mutex in | |
4778 | +** cases where it really needs one. {END} If a faster non-recursive mutex | |
4779 | +** implementation is available on the host platform, the mutex subsystem | |
4780 | +** might return such a mutex in response to SQLITE_MUTEX_FAST. | |
4781 | +** | |
4782 | +** {H17017} The other allowed parameters to sqlite3_mutex_alloc() each return | |
4783 | +** a pointer to a static preexisting mutex. {END} Six static mutexes are | |
4784 | +** used by the current version of SQLite. Future versions of SQLite | |
4785 | +** may add additional static mutexes. Static mutexes are for internal | |
4786 | +** use by SQLite only. Applications that use SQLite mutexes should | |
4787 | +** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or | |
4788 | +** SQLITE_MUTEX_RECURSIVE. | |
4789 | +** | |
4790 | +** {H17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST | |
4791 | +** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() | |
4792 | +** returns a different mutex on every call. {H17034} But for the static | |
4793 | +** mutex types, the same mutex is returned on every call that has | |
4794 | +** the same type number. | |
4795 | +** | |
4796 | +** {H17019} The sqlite3_mutex_free() routine deallocates a previously | |
4797 | +** allocated dynamic mutex. {H17020} SQLite is careful to deallocate every | |
4798 | +** dynamic mutex that it allocates. {A17021} The dynamic mutexes must not be in | |
4799 | +** use when they are deallocated. {A17022} Attempting to deallocate a static | |
4800 | +** mutex results in undefined behavior. {H17023} SQLite never deallocates | |
4801 | +** a static mutex. {END} | |
4802 | +** | |
4803 | +** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt | |
4804 | +** to enter a mutex. {H17024} If another thread is already within the mutex, | |
4805 | +** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return | |
4806 | +** SQLITE_BUSY. {H17025} The sqlite3_mutex_try() interface returns [SQLITE_OK] | |
4807 | +** upon successful entry. {H17026} Mutexes created using | |
4808 | +** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread. | |
4809 | +** {H17027} In such cases the, | |
4810 | +** mutex must be exited an equal number of times before another thread | |
4811 | +** can enter. {A17028} If the same thread tries to enter any other | |
4812 | +** kind of mutex more than once, the behavior is undefined. | |
4813 | +** {H17029} SQLite will never exhibit | |
4814 | +** such behavior in its own use of mutexes. | |
4815 | +** | |
4816 | +** Some systems (for example, Windows 95) do not support the operation | |
4817 | +** implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() | |
4818 | +** will always return SQLITE_BUSY. {H17030} The SQLite core only ever uses | |
4819 | +** sqlite3_mutex_try() as an optimization so this is acceptable behavior. | |
4820 | +** | |
4821 | +** {H17031} The sqlite3_mutex_leave() routine exits a mutex that was | |
4822 | +** previously entered by the same thread. {A17032} The behavior | |
4823 | +** is undefined if the mutex is not currently entered by the | |
4824 | +** calling thread or is not currently allocated. {H17033} SQLite will | |
4825 | +** never do either. {END} | |
4826 | +** | |
4827 | +** If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or | |
4828 | +** sqlite3_mutex_leave() is a NULL pointer, then all three routines | |
4829 | +** behave as no-ops. | |
4830 | +** | |
4831 | +** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()]. | |
2643 | 4832 | */ |
2644 | -int sqlite3_blob_close(sqlite3_blob *); | |
4833 | +SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int); | |
4834 | +SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*); | |
4835 | +SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*); | |
4836 | +SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*); | |
4837 | +SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*); | |
2645 | 4838 | |
2646 | 4839 | /* |
2647 | -** CAPI3REF: Return The Size Of An Open BLOB | |
4840 | +** CAPI3REF: Mutex Methods Object {H17120} <S20130> | |
4841 | +** EXPERIMENTAL | |
4842 | +** | |
4843 | +** An instance of this structure defines the low-level routines | |
4844 | +** used to allocate and use mutexes. | |
4845 | +** | |
4846 | +** Usually, the default mutex implementations provided by SQLite are | |
4847 | +** sufficient, however the user has the option of substituting a custom | |
4848 | +** implementation for specialized deployments or systems for which SQLite | |
4849 | +** does not provide a suitable implementation. In this case, the user | |
4850 | +** creates and populates an instance of this structure to pass | |
4851 | +** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option. | |
4852 | +** Additionally, an instance of this structure can be used as an | |
4853 | +** output variable when querying the system for the current mutex | |
4854 | +** implementation, using the [SQLITE_CONFIG_GETMUTEX] option. | |
4855 | +** | |
4856 | +** The xMutexInit method defined by this structure is invoked as | |
4857 | +** part of system initialization by the sqlite3_initialize() function. | |
4858 | +** {H17001} The xMutexInit routine shall be called by SQLite once for each | |
4859 | +** effective call to [sqlite3_initialize()]. | |
4860 | +** | |
4861 | +** The xMutexEnd method defined by this structure is invoked as | |
4862 | +** part of system shutdown by the sqlite3_shutdown() function. The | |
4863 | +** implementation of this method is expected to release all outstanding | |
4864 | +** resources obtained by the mutex methods implementation, especially | |
4865 | +** those obtained by the xMutexInit method. {H17003} The xMutexEnd() | |
4866 | +** interface shall be invoked once for each call to [sqlite3_shutdown()]. | |
4867 | +** | |
4868 | +** The remaining seven methods defined by this structure (xMutexAlloc, | |
4869 | +** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and | |
4870 | +** xMutexNotheld) implement the following interfaces (respectively): | |
4871 | +** | |
4872 | +** <ul> | |
4873 | +** <li> [sqlite3_mutex_alloc()] </li> | |
4874 | +** <li> [sqlite3_mutex_free()] </li> | |
4875 | +** <li> [sqlite3_mutex_enter()] </li> | |
4876 | +** <li> [sqlite3_mutex_try()] </li> | |
4877 | +** <li> [sqlite3_mutex_leave()] </li> | |
4878 | +** <li> [sqlite3_mutex_held()] </li> | |
4879 | +** <li> [sqlite3_mutex_notheld()] </li> | |
4880 | +** </ul> | |
2648 | 4881 | ** |
2649 | -** Return the size in bytes of the blob accessible via the open | |
2650 | -** [sqlite3_blob | blob-handle] passed as an argument. | |
4882 | +** The only difference is that the public sqlite3_XXX functions enumerated | |
4883 | +** above silently ignore any invocations that pass a NULL pointer instead | |
4884 | +** of a valid mutex handle. The implementations of the methods defined | |
4885 | +** by this structure are not required to handle this case, the results | |
4886 | +** of passing a NULL pointer instead of a valid mutex handle are undefined | |
4887 | +** (i.e. it is acceptable to provide an implementation that segfaults if | |
4888 | +** it is passed a NULL pointer). | |
4889 | +** | |
4890 | +** The xMutexInit() method must be threadsafe. It must be harmless to | |
4891 | +** invoke xMutexInit() mutiple times within the same process and without | |
4892 | +** intervening calls to xMutexEnd(). Second and subsequent calls to | |
4893 | +** xMutexInit() must be no-ops. | |
4894 | +** | |
4895 | +** xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()] | |
4896 | +** and its associates). Similarly, xMutexAlloc() must not use SQLite memory | |
4897 | +** allocation for a static mutex. However xMutexAlloc() may use SQLite | |
4898 | +** memory allocation for a fast or recursive mutex. | |
4899 | +** | |
4900 | +** SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is | |
4901 | +** called, but only if the prior call to xMutexInit returned SQLITE_OK. | |
4902 | +** If xMutexInit fails in any way, it is expected to clean up after itself | |
4903 | +** prior to returning. | |
2651 | 4904 | */ |
2652 | -int sqlite3_blob_bytes(sqlite3_blob *); | |
4905 | +typedef struct sqlite3_mutex_methods sqlite3_mutex_methods; | |
4906 | +struct sqlite3_mutex_methods { | |
4907 | + int (*xMutexInit)(void); | |
4908 | + int (*xMutexEnd)(void); | |
4909 | + sqlite3_mutex *(*xMutexAlloc)(int); | |
4910 | + void (*xMutexFree)(sqlite3_mutex *); | |
4911 | + void (*xMutexEnter)(sqlite3_mutex *); | |
4912 | + int (*xMutexTry)(sqlite3_mutex *); | |
4913 | + void (*xMutexLeave)(sqlite3_mutex *); | |
4914 | + int (*xMutexHeld)(sqlite3_mutex *); | |
4915 | + int (*xMutexNotheld)(sqlite3_mutex *); | |
4916 | +}; | |
4917 | + | |
4918 | +/* | |
4919 | +** CAPI3REF: Mutex Verification Routines {H17080} <S20130> <S30800> | |
4920 | +** | |
4921 | +** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines | |
4922 | +** are intended for use inside assert() statements. {H17081} The SQLite core | |
4923 | +** never uses these routines except inside an assert() and applications | |
4924 | +** are advised to follow the lead of the core. {H17082} The core only | |
4925 | +** provides implementations for these routines when it is compiled | |
4926 | +** with the SQLITE_DEBUG flag. {A17087} External mutex implementations | |
4927 | +** are only required to provide these routines if SQLITE_DEBUG is | |
4928 | +** defined and if NDEBUG is not defined. | |
4929 | +** | |
4930 | +** {H17083} These routines should return true if the mutex in their argument | |
4931 | +** is held or not held, respectively, by the calling thread. | |
4932 | +** | |
4933 | +** {X17084} The implementation is not required to provided versions of these | |
4934 | +** routines that actually work. If the implementation does not provide working | |
4935 | +** versions of these routines, it should at least provide stubs that always | |
4936 | +** return true so that one does not get spurious assertion failures. | |
4937 | +** | |
4938 | +** {H17085} If the argument to sqlite3_mutex_held() is a NULL pointer then | |
4939 | +** the routine should return 1. {END} This seems counter-intuitive since | |
4940 | +** clearly the mutex cannot be held if it does not exist. But the | |
4941 | +** the reason the mutex does not exist is because the build is not | |
4942 | +** using mutexes. And we do not want the assert() containing the | |
4943 | +** call to sqlite3_mutex_held() to fail, so a non-zero return is | |
4944 | +** the appropriate thing to do. {H17086} The sqlite3_mutex_notheld() | |
4945 | +** interface should also return 1 when given a NULL pointer. | |
4946 | +*/ | |
4947 | +SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*); | |
4948 | +SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*); | |
2653 | 4949 | |
2654 | 4950 | /* |
2655 | -** CAPI3REF: Read Data From A BLOB Incrementally | |
4951 | +** CAPI3REF: Mutex Types {H17001} <H17000> | |
2656 | 4952 | ** |
2657 | -** This function is used to read data from an open | |
2658 | -** [sqlite3_blob | blob-handle] into a caller supplied buffer. | |
2659 | -** n bytes of data are copied into buffer | |
2660 | -** z from the open blob, starting at offset iOffset. | |
4953 | +** The [sqlite3_mutex_alloc()] interface takes a single argument | |
4954 | +** which is one of these integer constants. | |
2661 | 4955 | ** |
2662 | -** On success, SQLITE_OK is returned. Otherwise, an | |
2663 | -** [SQLITE_ERROR | SQLite error code] or an | |
2664 | -** [SQLITE_IOERR_READ | extended error code] is returned. | |
4956 | +** The set of static mutexes may change from one SQLite release to the | |
4957 | +** next. Applications that override the built-in mutex logic must be | |
4958 | +** prepared to accommodate additional static mutexes. | |
2665 | 4959 | */ |
2666 | -int sqlite3_blob_read(sqlite3_blob *, void *z, int n, int iOffset); | |
4960 | +#define SQLITE_MUTEX_FAST 0 | |
4961 | +#define SQLITE_MUTEX_RECURSIVE 1 | |
4962 | +#define SQLITE_MUTEX_STATIC_MASTER 2 | |
4963 | +#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ | |
4964 | +#define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */ | |
4965 | +#define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */ | |
4966 | +#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */ | |
4967 | +#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ | |
4968 | +#define SQLITE_MUTEX_STATIC_LRU2 7 /* lru page list */ | |
2667 | 4969 | |
2668 | 4970 | /* |
2669 | -** CAPI3REF: Write Data Into A BLOB Incrementally | |
4971 | +** CAPI3REF: Retrieve the mutex for a database connection {H17002} <H17000> | |
2670 | 4972 | ** |
2671 | -** This function is used to write data into an open | |
2672 | -** [sqlite3_blob | blob-handle] from a user supplied buffer. | |
2673 | -** n bytes of data are copied from the buffer | |
2674 | -** pointed to by z into the open blob, starting at offset iOffset. | |
4973 | +** This interface returns a pointer the [sqlite3_mutex] object that | |
4974 | +** serializes access to the [database connection] given in the argument | |
4975 | +** when the [threading mode] is Serialized. | |
4976 | +** If the [threading mode] is Single-thread or Multi-thread then this | |
4977 | +** routine returns a NULL pointer. | |
4978 | +*/ | |
4979 | +SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*); | |
4980 | + | |
4981 | +/* | |
4982 | +** CAPI3REF: Low-Level Control Of Database Files {H11300} <S30800> | |
4983 | +** | |
4984 | +** {H11301} The [sqlite3_file_control()] interface makes a direct call to the | |
4985 | +** xFileControl method for the [sqlite3_io_methods] object associated | |
4986 | +** with a particular database identified by the second argument. {H11302} The | |
4987 | +** name of the database is the name assigned to the database by the | |
4988 | +** <a href="lang_attach.html">ATTACH</a> SQL command that opened the | |
4989 | +** database. {H11303} To control the main database file, use the name "main" | |
4990 | +** or a NULL pointer. {H11304} The third and fourth parameters to this routine | |
4991 | +** are passed directly through to the second and third parameters of | |
4992 | +** the xFileControl method. {H11305} The return value of the xFileControl | |
4993 | +** method becomes the return value of this routine. | |
4994 | +** | |
4995 | +** {H11306} If the second parameter (zDbName) does not match the name of any | |
4996 | +** open database file, then SQLITE_ERROR is returned. {H11307} This error | |
4997 | +** code is not remembered and will not be recalled by [sqlite3_errcode()] | |
4998 | +** or [sqlite3_errmsg()]. {A11308} The underlying xFileControl method might | |
4999 | +** also return SQLITE_ERROR. {A11309} There is no way to distinguish between | |
5000 | +** an incorrect zDbName and an SQLITE_ERROR return from the underlying | |
5001 | +** xFileControl method. {END} | |
5002 | +** | |
5003 | +** See also: [SQLITE_FCNTL_LOCKSTATE] | |
5004 | +*/ | |
5005 | +SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); | |
5006 | + | |
5007 | +/* | |
5008 | +** CAPI3REF: Testing Interface {H11400} <S30800> | |
2675 | 5009 | ** |
2676 | -** If the [sqlite3_blob | blob-handle] passed as the first argument | |
2677 | -** was not opened for writing (the flags parameter to [sqlite3_blob_open()] | |
2678 | -*** was zero), this function returns [SQLITE_READONLY]. | |
5010 | +** The sqlite3_test_control() interface is used to read out internal | |
5011 | +** state of SQLite and to inject faults into SQLite for testing | |
5012 | +** purposes. The first parameter is an operation code that determines | |
5013 | +** the number, meaning, and operation of all subsequent parameters. | |
2679 | 5014 | ** |
2680 | -** This function may only modify the contents of the blob, it is | |
2681 | -** not possible to increase the size of a blob using this API. If | |
2682 | -** offset iOffset is less than n bytes from the end of the blob, | |
2683 | -** [SQLITE_ERROR] is returned and no data is written. | |
5015 | +** This interface is not for use by applications. It exists solely | |
5016 | +** for verifying the correct operation of the SQLite library. Depending | |
5017 | +** on how the SQLite library is compiled, this interface might not exist. | |
2684 | 5018 | ** |
2685 | -** On success, SQLITE_OK is returned. Otherwise, an | |
2686 | -** [SQLITE_ERROR | SQLite error code] or an | |
2687 | -** [SQLITE_IOERR_READ | extended error code] is returned. | |
5019 | +** The details of the operation codes, their meanings, the parameters | |
5020 | +** they take, and what they do are all subject to change without notice. | |
5021 | +** Unlike most of the SQLite API, this function is not guaranteed to | |
5022 | +** operate consistently from one release to the next. | |
2688 | 5023 | */ |
2689 | -int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); | |
5024 | +SQLITE_API int sqlite3_test_control(int op, ...); | |
5025 | + | |
5026 | +/* | |
5027 | +** CAPI3REF: Testing Interface Operation Codes {H11410} <H11400> | |
5028 | +** | |
5029 | +** These constants are the valid operation code parameters used | |
5030 | +** as the first argument to [sqlite3_test_control()]. | |
5031 | +** | |
5032 | +** These parameters and their meanings are subject to change | |
5033 | +** without notice. These values are for testing purposes only. | |
5034 | +** Applications should not use any of these parameters or the | |
5035 | +** [sqlite3_test_control()] interface. | |
5036 | +*/ | |
5037 | +#define SQLITE_TESTCTRL_PRNG_SAVE 5 | |
5038 | +#define SQLITE_TESTCTRL_PRNG_RESTORE 6 | |
5039 | +#define SQLITE_TESTCTRL_PRNG_RESET 7 | |
5040 | +#define SQLITE_TESTCTRL_BITVEC_TEST 8 | |
5041 | +#define SQLITE_TESTCTRL_FAULT_INSTALL 9 | |
5042 | +#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 | |
5043 | +#define SQLITE_TESTCTRL_PENDING_BYTE 11 | |
5044 | +#define SQLITE_TESTCTRL_ASSERT 12 | |
5045 | +#define SQLITE_TESTCTRL_ALWAYS 13 | |
5046 | +#define SQLITE_TESTCTRL_RESERVE 14 | |
5047 | + | |
5048 | +/* | |
5049 | +** CAPI3REF: SQLite Runtime Status {H17200} <S60200> | |
5050 | +** EXPERIMENTAL | |
5051 | +** | |
5052 | +** This interface is used to retrieve runtime status information | |
5053 | +** about the preformance of SQLite, and optionally to reset various | |
5054 | +** highwater marks. The first argument is an integer code for | |
5055 | +** the specific parameter to measure. Recognized integer codes | |
5056 | +** are of the form [SQLITE_STATUS_MEMORY_USED | SQLITE_STATUS_...]. | |
5057 | +** The current value of the parameter is returned into *pCurrent. | |
5058 | +** The highest recorded value is returned in *pHighwater. If the | |
5059 | +** resetFlag is true, then the highest record value is reset after | |
5060 | +** *pHighwater is written. Some parameters do not record the highest | |
5061 | +** value. For those parameters | |
5062 | +** nothing is written into *pHighwater and the resetFlag is ignored. | |
5063 | +** Other parameters record only the highwater mark and not the current | |
5064 | +** value. For these latter parameters nothing is written into *pCurrent. | |
5065 | +** | |
5066 | +** This routine returns SQLITE_OK on success and a non-zero | |
5067 | +** [error code] on failure. | |
5068 | +** | |
5069 | +** This routine is threadsafe but is not atomic. This routine can be | |
5070 | +** called while other threads are running the same or different SQLite | |
5071 | +** interfaces. However the values returned in *pCurrent and | |
5072 | +** *pHighwater reflect the status of SQLite at different points in time | |
5073 | +** and it is possible that another thread might change the parameter | |
5074 | +** in between the times when *pCurrent and *pHighwater are written. | |
5075 | +** | |
5076 | +** See also: [sqlite3_db_status()] | |
5077 | +*/ | |
5078 | +SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag); | |
5079 | + | |
5080 | + | |
5081 | +/* | |
5082 | +** CAPI3REF: Status Parameters {H17250} <H17200> | |
5083 | +** EXPERIMENTAL | |
5084 | +** | |
5085 | +** These integer constants designate various run-time status parameters | |
5086 | +** that can be returned by [sqlite3_status()]. | |
5087 | +** | |
5088 | +** <dl> | |
5089 | +** <dt>SQLITE_STATUS_MEMORY_USED</dt> | |
5090 | +** <dd>This parameter is the current amount of memory checked out | |
5091 | +** using [sqlite3_malloc()], either directly or indirectly. The | |
5092 | +** figure includes calls made to [sqlite3_malloc()] by the application | |
5093 | +** and internal memory usage by the SQLite library. Scratch memory | |
5094 | +** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache | |
5095 | +** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in | |
5096 | +** this parameter. The amount returned is the sum of the allocation | |
5097 | +** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd> | |
5098 | +** | |
5099 | +** <dt>SQLITE_STATUS_MALLOC_SIZE</dt> | |
5100 | +** <dd>This parameter records the largest memory allocation request | |
5101 | +** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their | |
5102 | +** internal equivalents). Only the value returned in the | |
5103 | +** *pHighwater parameter to [sqlite3_status()] is of interest. | |
5104 | +** The value written into the *pCurrent parameter is undefined.</dd> | |
5105 | +** | |
5106 | +** <dt>SQLITE_STATUS_PAGECACHE_USED</dt> | |
5107 | +** <dd>This parameter returns the number of pages used out of the | |
5108 | +** [pagecache memory allocator] that was configured using | |
5109 | +** [SQLITE_CONFIG_PAGECACHE]. The | |
5110 | +** value returned is in pages, not in bytes.</dd> | |
5111 | +** | |
5112 | +** <dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt> | |
5113 | +** <dd>This parameter returns the number of bytes of page cache | |
5114 | +** allocation which could not be statisfied by the [SQLITE_CONFIG_PAGECACHE] | |
5115 | +** buffer and where forced to overflow to [sqlite3_malloc()]. The | |
5116 | +** returned value includes allocations that overflowed because they | |
5117 | +** where too large (they were larger than the "sz" parameter to | |
5118 | +** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because | |
5119 | +** no space was left in the page cache.</dd> | |
5120 | +** | |
5121 | +** <dt>SQLITE_STATUS_PAGECACHE_SIZE</dt> | |
5122 | +** <dd>This parameter records the largest memory allocation request | |
5123 | +** handed to [pagecache memory allocator]. Only the value returned in the | |
5124 | +** *pHighwater parameter to [sqlite3_status()] is of interest. | |
5125 | +** The value written into the *pCurrent parameter is undefined.</dd> | |
5126 | +** | |
5127 | +** <dt>SQLITE_STATUS_SCRATCH_USED</dt> | |
5128 | +** <dd>This parameter returns the number of allocations used out of the | |
5129 | +** [scratch memory allocator] configured using | |
5130 | +** [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not | |
5131 | +** in bytes. Since a single thread may only have one scratch allocation | |
5132 | +** outstanding at time, this parameter also reports the number of threads | |
5133 | +** using scratch memory at the same time.</dd> | |
5134 | +** | |
5135 | +** <dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt> | |
5136 | +** <dd>This parameter returns the number of bytes of scratch memory | |
5137 | +** allocation which could not be statisfied by the [SQLITE_CONFIG_SCRATCH] | |
5138 | +** buffer and where forced to overflow to [sqlite3_malloc()]. The values | |
5139 | +** returned include overflows because the requested allocation was too | |
5140 | +** larger (that is, because the requested allocation was larger than the | |
5141 | +** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer | |
5142 | +** slots were available. | |
5143 | +** </dd> | |
5144 | +** | |
5145 | +** <dt>SQLITE_STATUS_SCRATCH_SIZE</dt> | |
5146 | +** <dd>This parameter records the largest memory allocation request | |
5147 | +** handed to [scratch memory allocator]. Only the value returned in the | |
5148 | +** *pHighwater parameter to [sqlite3_status()] is of interest. | |
5149 | +** The value written into the *pCurrent parameter is undefined.</dd> | |
5150 | +** | |
5151 | +** <dt>SQLITE_STATUS_PARSER_STACK</dt> | |
5152 | +** <dd>This parameter records the deepest parser stack. It is only | |
5153 | +** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd> | |
5154 | +** </dl> | |
5155 | +** | |
5156 | +** New status parameters may be added from time to time. | |
5157 | +*/ | |
5158 | +#define SQLITE_STATUS_MEMORY_USED 0 | |
5159 | +#define SQLITE_STATUS_PAGECACHE_USED 1 | |
5160 | +#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2 | |
5161 | +#define SQLITE_STATUS_SCRATCH_USED 3 | |
5162 | +#define SQLITE_STATUS_SCRATCH_OVERFLOW 4 | |
5163 | +#define SQLITE_STATUS_MALLOC_SIZE 5 | |
5164 | +#define SQLITE_STATUS_PARSER_STACK 6 | |
5165 | +#define SQLITE_STATUS_PAGECACHE_SIZE 7 | |
5166 | +#define SQLITE_STATUS_SCRATCH_SIZE 8 | |
5167 | + | |
5168 | +/* | |
5169 | +** CAPI3REF: Database Connection Status {H17500} <S60200> | |
5170 | +** EXPERIMENTAL | |
5171 | +** | |
5172 | +** This interface is used to retrieve runtime status information | |
5173 | +** about a single [database connection]. The first argument is the | |
5174 | +** database connection object to be interrogated. The second argument | |
5175 | +** is the parameter to interrogate. Currently, the only allowed value | |
5176 | +** for the second parameter is [SQLITE_DBSTATUS_LOOKASIDE_USED]. | |
5177 | +** Additional options will likely appear in future releases of SQLite. | |
5178 | +** | |
5179 | +** The current value of the requested parameter is written into *pCur | |
5180 | +** and the highest instantaneous value is written into *pHiwtr. If | |
5181 | +** the resetFlg is true, then the highest instantaneous value is | |
5182 | +** reset back down to the current value. | |
5183 | +** | |
5184 | +** See also: [sqlite3_status()] and [sqlite3_stmt_status()]. | |
5185 | +*/ | |
5186 | +SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg); | |
5187 | + | |
5188 | +/* | |
5189 | +** CAPI3REF: Status Parameters for database connections {H17520} <H17500> | |
5190 | +** EXPERIMENTAL | |
5191 | +** | |
5192 | +** These constants are the available integer "verbs" that can be passed as | |
5193 | +** the second argument to the [sqlite3_db_status()] interface. | |
5194 | +** | |
5195 | +** New verbs may be added in future releases of SQLite. Existing verbs | |
5196 | +** might be discontinued. Applications should check the return code from | |
5197 | +** [sqlite3_db_status()] to make sure that the call worked. | |
5198 | +** The [sqlite3_db_status()] interface will return a non-zero error code | |
5199 | +** if a discontinued or unsupported verb is invoked. | |
5200 | +** | |
5201 | +** <dl> | |
5202 | +** <dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt> | |
5203 | +** <dd>This parameter returns the number of lookaside memory slots currently | |
5204 | +** checked out.</dd> | |
5205 | +** </dl> | |
5206 | +*/ | |
5207 | +#define SQLITE_DBSTATUS_LOOKASIDE_USED 0 | |
5208 | + | |
5209 | + | |
5210 | +/* | |
5211 | +** CAPI3REF: Prepared Statement Status {H17550} <S60200> | |
5212 | +** EXPERIMENTAL | |
5213 | +** | |
5214 | +** Each prepared statement maintains various | |
5215 | +** [SQLITE_STMTSTATUS_SORT | counters] that measure the number | |
5216 | +** of times it has performed specific operations. These counters can | |
5217 | +** be used to monitor the performance characteristics of the prepared | |
5218 | +** statements. For example, if the number of table steps greatly exceeds | |
5219 | +** the number of table searches or result rows, that would tend to indicate | |
5220 | +** that the prepared statement is using a full table scan rather than | |
5221 | +** an index. | |
5222 | +** | |
5223 | +** This interface is used to retrieve and reset counter values from | |
5224 | +** a [prepared statement]. The first argument is the prepared statement | |
5225 | +** object to be interrogated. The second argument | |
5226 | +** is an integer code for a specific [SQLITE_STMTSTATUS_SORT | counter] | |
5227 | +** to be interrogated. | |
5228 | +** The current value of the requested counter is returned. | |
5229 | +** If the resetFlg is true, then the counter is reset to zero after this | |
5230 | +** interface call returns. | |
5231 | +** | |
5232 | +** See also: [sqlite3_status()] and [sqlite3_db_status()]. | |
5233 | +*/ | |
5234 | +SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg); | |
5235 | + | |
5236 | +/* | |
5237 | +** CAPI3REF: Status Parameters for prepared statements {H17570} <H17550> | |
5238 | +** EXPERIMENTAL | |
5239 | +** | |
5240 | +** These preprocessor macros define integer codes that name counter | |
5241 | +** values associated with the [sqlite3_stmt_status()] interface. | |
5242 | +** The meanings of the various counters are as follows: | |
5243 | +** | |
5244 | +** <dl> | |
5245 | +** <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt> | |
5246 | +** <dd>This is the number of times that SQLite has stepped forward in | |
5247 | +** a table as part of a full table scan. Large numbers for this counter | |
5248 | +** may indicate opportunities for performance improvement through | |
5249 | +** careful use of indices.</dd> | |
5250 | +** | |
5251 | +** <dt>SQLITE_STMTSTATUS_SORT</dt> | |
5252 | +** <dd>This is the number of sort operations that have occurred. | |
5253 | +** A non-zero value in this counter may indicate an opportunity to | |
5254 | +** improvement performance through careful use of indices.</dd> | |
5255 | +** | |
5256 | +** </dl> | |
5257 | +*/ | |
5258 | +#define SQLITE_STMTSTATUS_FULLSCAN_STEP 1 | |
5259 | +#define SQLITE_STMTSTATUS_SORT 2 | |
5260 | + | |
5261 | +/* | |
5262 | +** CAPI3REF: Custom Page Cache Object | |
5263 | +** EXPERIMENTAL | |
5264 | +** | |
5265 | +** The sqlite3_pcache type is opaque. It is implemented by | |
5266 | +** the pluggable module. The SQLite core has no knowledge of | |
5267 | +** its size or internal structure and never deals with the | |
5268 | +** sqlite3_pcache object except by holding and passing pointers | |
5269 | +** to the object. | |
5270 | +** | |
5271 | +** See [sqlite3_pcache_methods] for additional information. | |
5272 | +*/ | |
5273 | +typedef struct sqlite3_pcache sqlite3_pcache; | |
5274 | + | |
5275 | +/* | |
5276 | +** CAPI3REF: Application Defined Page Cache. | |
5277 | +** KEYWORDS: {page cache} | |
5278 | +** EXPERIMENTAL | |
5279 | +** | |
5280 | +** The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can | |
5281 | +** register an alternative page cache implementation by passing in an | |
5282 | +** instance of the sqlite3_pcache_methods structure. The majority of the | |
5283 | +** heap memory used by SQLite is used by the page cache to cache data read | |
5284 | +** from, or ready to be written to, the database file. By implementing a | |
5285 | +** custom page cache using this API, an application can control more | |
5286 | +** precisely the amount of memory consumed by SQLite, the way in which | |
5287 | +** that memory is allocated and released, and the policies used to | |
5288 | +** determine exactly which parts of a database file are cached and for | |
5289 | +** how long. | |
5290 | +** | |
5291 | +** The contents of the sqlite3_pcache_methods structure are copied to an | |
5292 | +** internal buffer by SQLite within the call to [sqlite3_config]. Hence | |
5293 | +** the application may discard the parameter after the call to | |
5294 | +** [sqlite3_config()] returns. | |
5295 | +** | |
5296 | +** The xInit() method is called once for each call to [sqlite3_initialize()] | |
5297 | +** (usually only once during the lifetime of the process). It is passed | |
5298 | +** a copy of the sqlite3_pcache_methods.pArg value. It can be used to set | |
5299 | +** up global structures and mutexes required by the custom page cache | |
5300 | +** implementation. | |
5301 | +** | |
5302 | +** The xShutdown() method is called from within [sqlite3_shutdown()], | |
5303 | +** if the application invokes this API. It can be used to clean up | |
5304 | +** any outstanding resources before process shutdown, if required. | |
5305 | +** | |
5306 | +** SQLite holds a [SQLITE_MUTEX_RECURSIVE] mutex when it invokes | |
5307 | +** the xInit method, so the xInit method need not be threadsafe. The | |
5308 | +** xShutdown method is only called from [sqlite3_shutdown()] so it does | |
5309 | +** not need to be threadsafe either. All other methods must be threadsafe | |
5310 | +** in multithreaded applications. | |
5311 | +** | |
5312 | +** SQLite will never invoke xInit() more than once without an intervening | |
5313 | +** call to xShutdown(). | |
5314 | +** | |
5315 | +** The xCreate() method is used to construct a new cache instance. SQLite | |
5316 | +** will typically create one cache instance for each open database file, | |
5317 | +** though this is not guaranteed. The | |
5318 | +** first parameter, szPage, is the size in bytes of the pages that must | |
5319 | +** be allocated by the cache. szPage will not be a power of two. szPage | |
5320 | +** will the page size of the database file that is to be cached plus an | |
5321 | +** increment (here called "R") of about 100 or 200. SQLite will use the | |
5322 | +** extra R bytes on each page to store metadata about the underlying | |
5323 | +** database page on disk. The value of R depends | |
5324 | +** on the SQLite version, the target platform, and how SQLite was compiled. | |
5325 | +** R is constant for a particular build of SQLite. The second argument to | |
5326 | +** xCreate(), bPurgeable, is true if the cache being created will | |
5327 | +** be used to cache database pages of a file stored on disk, or | |
5328 | +** false if it is used for an in-memory database. The cache implementation | |
5329 | +** does not have to do anything special based with the value of bPurgeable; | |
5330 | +** it is purely advisory. On a cache where bPurgeable is false, SQLite will | |
5331 | +** never invoke xUnpin() except to deliberately delete a page. | |
5332 | +** In other words, a cache created with bPurgeable set to false will | |
5333 | +** never contain any unpinned pages. | |
5334 | +** | |
5335 | +** The xCachesize() method may be called at any time by SQLite to set the | |
5336 | +** suggested maximum cache-size (number of pages stored by) the cache | |
5337 | +** instance passed as the first argument. This is the value configured using | |
5338 | +** the SQLite "[PRAGMA cache_size]" command. As with the bPurgeable parameter, | |
5339 | +** the implementation is not required to do anything with this | |
5340 | +** value; it is advisory only. | |
5341 | +** | |
5342 | +** The xPagecount() method should return the number of pages currently | |
5343 | +** stored in the cache. | |
5344 | +** | |
5345 | +** The xFetch() method is used to fetch a page and return a pointer to it. | |
5346 | +** A 'page', in this context, is a buffer of szPage bytes aligned at an | |
5347 | +** 8-byte boundary. The page to be fetched is determined by the key. The | |
5348 | +** mimimum key value is 1. After it has been retrieved using xFetch, the page | |
5349 | +** is considered to be "pinned". | |
5350 | +** | |
5351 | +** If the requested page is already in the page cache, then the page cache | |
5352 | +** implementation must return a pointer to the page buffer with its content | |
5353 | +** intact. If the requested page is not already in the cache, then the | |
5354 | +** behavior of the cache implementation is determined by the value of the | |
5355 | +** createFlag parameter passed to xFetch, according to the following table: | |
5356 | +** | |
5357 | +** <table border=1 width=85% align=center> | |
5358 | +** <tr><th> createFlag <th> Behaviour when page is not already in cache | |
5359 | +** <tr><td> 0 <td> Do not allocate a new page. Return NULL. | |
5360 | +** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so. | |
5361 | +** Otherwise return NULL. | |
5362 | +** <tr><td> 2 <td> Make every effort to allocate a new page. Only return | |
5363 | +** NULL if allocating a new page is effectively impossible. | |
5364 | +** </table> | |
5365 | +** | |
5366 | +** SQLite will normally invoke xFetch() with a createFlag of 0 or 1. If | |
5367 | +** a call to xFetch() with createFlag==1 returns NULL, then SQLite will | |
5368 | +** attempt to unpin one or more cache pages by spilling the content of | |
5369 | +** pinned pages to disk and synching the operating system disk cache. After | |
5370 | +** attempting to unpin pages, the xFetch() method will be invoked again with | |
5371 | +** a createFlag of 2. | |
5372 | +** | |
5373 | +** xUnpin() is called by SQLite with a pointer to a currently pinned page | |
5374 | +** as its second argument. If the third parameter, discard, is non-zero, | |
5375 | +** then the page should be evicted from the cache. In this case SQLite | |
5376 | +** assumes that the next time the page is retrieved from the cache using | |
5377 | +** the xFetch() method, it will be zeroed. If the discard parameter is | |
5378 | +** zero, then the page is considered to be unpinned. The cache implementation | |
5379 | +** may choose to evict unpinned pages at any time. | |
5380 | +** | |
5381 | +** The cache is not required to perform any reference counting. A single | |
5382 | +** call to xUnpin() unpins the page regardless of the number of prior calls | |
5383 | +** to xFetch(). | |
5384 | +** | |
5385 | +** The xRekey() method is used to change the key value associated with the | |
5386 | +** page passed as the second argument from oldKey to newKey. If the cache | |
5387 | +** previously contains an entry associated with newKey, it should be | |
5388 | +** discarded. Any prior cache entry associated with newKey is guaranteed not | |
5389 | +** to be pinned. | |
5390 | +** | |
5391 | +** When SQLite calls the xTruncate() method, the cache must discard all | |
5392 | +** existing cache entries with page numbers (keys) greater than or equal | |
5393 | +** to the value of the iLimit parameter passed to xTruncate(). If any | |
5394 | +** of these pages are pinned, they are implicitly unpinned, meaning that | |
5395 | +** they can be safely discarded. | |
5396 | +** | |
5397 | +** The xDestroy() method is used to delete a cache allocated by xCreate(). | |
5398 | +** All resources associated with the specified cache should be freed. After | |
5399 | +** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*] | |
5400 | +** handle invalid, and will not use it with any other sqlite3_pcache_methods | |
5401 | +** functions. | |
5402 | +*/ | |
5403 | +typedef struct sqlite3_pcache_methods sqlite3_pcache_methods; | |
5404 | +struct sqlite3_pcache_methods { | |
5405 | + void *pArg; | |
5406 | + int (*xInit)(void*); | |
5407 | + void (*xShutdown)(void*); | |
5408 | + sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable); | |
5409 | + void (*xCachesize)(sqlite3_pcache*, int nCachesize); | |
5410 | + int (*xPagecount)(sqlite3_pcache*); | |
5411 | + void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag); | |
5412 | + void (*xUnpin)(sqlite3_pcache*, void*, int discard); | |
5413 | + void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey); | |
5414 | + void (*xTruncate)(sqlite3_pcache*, unsigned iLimit); | |
5415 | + void (*xDestroy)(sqlite3_pcache*); | |
5416 | +}; | |
5417 | + | |
5418 | +/* | |
5419 | +** CAPI3REF: Online Backup Object | |
5420 | +** EXPERIMENTAL | |
5421 | +** | |
5422 | +** The sqlite3_backup object records state information about an ongoing | |
5423 | +** online backup operation. The sqlite3_backup object is created by | |
5424 | +** a call to [sqlite3_backup_init()] and is destroyed by a call to | |
5425 | +** [sqlite3_backup_finish()]. | |
5426 | +** | |
5427 | +** See Also: [Using the SQLite Online Backup API] | |
5428 | +*/ | |
5429 | +typedef struct sqlite3_backup sqlite3_backup; | |
5430 | + | |
5431 | +/* | |
5432 | +** CAPI3REF: Online Backup API. | |
5433 | +** EXPERIMENTAL | |
5434 | +** | |
5435 | +** This API is used to overwrite the contents of one database with that | |
5436 | +** of another. It is useful either for creating backups of databases or | |
5437 | +** for copying in-memory databases to or from persistent files. | |
5438 | +** | |
5439 | +** See Also: [Using the SQLite Online Backup API] | |
5440 | +** | |
5441 | +** Exclusive access is required to the destination database for the | |
5442 | +** duration of the operation. However the source database is only | |
5443 | +** read-locked while it is actually being read, it is not locked | |
5444 | +** continuously for the entire operation. Thus, the backup may be | |
5445 | +** performed on a live database without preventing other users from | |
5446 | +** writing to the database for an extended period of time. | |
5447 | +** | |
5448 | +** To perform a backup operation: | |
5449 | +** <ol> | |
5450 | +** <li><b>sqlite3_backup_init()</b> is called once to initialize the | |
5451 | +** backup, | |
5452 | +** <li><b>sqlite3_backup_step()</b> is called one or more times to transfer | |
5453 | +** the data between the two databases, and finally | |
5454 | +** <li><b>sqlite3_backup_finish()</b> is called to release all resources | |
5455 | +** associated with the backup operation. | |
5456 | +** </ol> | |
5457 | +** There should be exactly one call to sqlite3_backup_finish() for each | |
5458 | +** successful call to sqlite3_backup_init(). | |
5459 | +** | |
5460 | +** <b>sqlite3_backup_init()</b> | |
5461 | +** | |
5462 | +** The first two arguments passed to [sqlite3_backup_init()] are the database | |
5463 | +** handle associated with the destination database and the database name | |
5464 | +** used to attach the destination database to the handle. The database name | |
5465 | +** is "main" for the main database, "temp" for the temporary database, or | |
5466 | +** the name specified as part of the [ATTACH] statement if the destination is | |
5467 | +** an attached database. The third and fourth arguments passed to | |
5468 | +** sqlite3_backup_init() identify the [database connection] | |
5469 | +** and database name used | |
5470 | +** to access the source database. The values passed for the source and | |
5471 | +** destination [database connection] parameters must not be the same. | |
5472 | +** | |
5473 | +** If an error occurs within sqlite3_backup_init(), then NULL is returned | |
5474 | +** and an error code and error message written into the [database connection] | |
5475 | +** passed as the first argument. They may be retrieved using the | |
5476 | +** [sqlite3_errcode()], [sqlite3_errmsg()], and [sqlite3_errmsg16()] functions. | |
5477 | +** Otherwise, if successful, a pointer to an [sqlite3_backup] object is | |
5478 | +** returned. This pointer may be used with the sqlite3_backup_step() and | |
5479 | +** sqlite3_backup_finish() functions to perform the specified backup | |
5480 | +** operation. | |
5481 | +** | |
5482 | +** <b>sqlite3_backup_step()</b> | |
5483 | +** | |
5484 | +** Function [sqlite3_backup_step()] is used to copy up to nPage pages between | |
5485 | +** the source and destination databases, where nPage is the value of the | |
5486 | +** second parameter passed to sqlite3_backup_step(). If nPage is a negative | |
5487 | +** value, all remaining source pages are copied. If the required pages are | |
5488 | +** succesfully copied, but there are still more pages to copy before the | |
5489 | +** backup is complete, it returns [SQLITE_OK]. If no error occured and there | |
5490 | +** are no more pages to copy, then [SQLITE_DONE] is returned. If an error | |
5491 | +** occurs, then an SQLite error code is returned. As well as [SQLITE_OK] and | |
5492 | +** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY], | |
5493 | +** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an | |
5494 | +** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code. | |
5495 | +** | |
5496 | +** As well as the case where the destination database file was opened for | |
5497 | +** read-only access, sqlite3_backup_step() may return [SQLITE_READONLY] if | |
5498 | +** the destination is an in-memory database with a different page size | |
5499 | +** from the source database. | |
5500 | +** | |
5501 | +** If sqlite3_backup_step() cannot obtain a required file-system lock, then | |
5502 | +** the [sqlite3_busy_handler | busy-handler function] | |
5503 | +** is invoked (if one is specified). If the | |
5504 | +** busy-handler returns non-zero before the lock is available, then | |
5505 | +** [SQLITE_BUSY] is returned to the caller. In this case the call to | |
5506 | +** sqlite3_backup_step() can be retried later. If the source | |
5507 | +** [database connection] | |
5508 | +** is being used to write to the source database when sqlite3_backup_step() | |
5509 | +** is called, then [SQLITE_LOCKED] is returned immediately. Again, in this | |
5510 | +** case the call to sqlite3_backup_step() can be retried later on. If | |
5511 | +** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or | |
5512 | +** [SQLITE_READONLY] is returned, then | |
5513 | +** there is no point in retrying the call to sqlite3_backup_step(). These | |
5514 | +** errors are considered fatal. At this point the application must accept | |
5515 | +** that the backup operation has failed and pass the backup operation handle | |
5516 | +** to the sqlite3_backup_finish() to release associated resources. | |
5517 | +** | |
5518 | +** Following the first call to sqlite3_backup_step(), an exclusive lock is | |
5519 | +** obtained on the destination file. It is not released until either | |
5520 | +** sqlite3_backup_finish() is called or the backup operation is complete | |
5521 | +** and sqlite3_backup_step() returns [SQLITE_DONE]. Additionally, each time | |
5522 | +** a call to sqlite3_backup_step() is made a [shared lock] is obtained on | |
5523 | +** the source database file. This lock is released before the | |
5524 | +** sqlite3_backup_step() call returns. Because the source database is not | |
5525 | +** locked between calls to sqlite3_backup_step(), it may be modified mid-way | |
5526 | +** through the backup procedure. If the source database is modified by an | |
5527 | +** external process or via a database connection other than the one being | |
5528 | +** used by the backup operation, then the backup will be transparently | |
5529 | +** restarted by the next call to sqlite3_backup_step(). If the source | |
5530 | +** database is modified by the using the same database connection as is used | |
5531 | +** by the backup operation, then the backup database is transparently | |
5532 | +** updated at the same time. | |
5533 | +** | |
5534 | +** <b>sqlite3_backup_finish()</b> | |
5535 | +** | |
5536 | +** Once sqlite3_backup_step() has returned [SQLITE_DONE], or when the | |
5537 | +** application wishes to abandon the backup operation, the [sqlite3_backup] | |
5538 | +** object should be passed to sqlite3_backup_finish(). This releases all | |
5539 | +** resources associated with the backup operation. If sqlite3_backup_step() | |
5540 | +** has not yet returned [SQLITE_DONE], then any active write-transaction on the | |
5541 | +** destination database is rolled back. The [sqlite3_backup] object is invalid | |
5542 | +** and may not be used following a call to sqlite3_backup_finish(). | |
5543 | +** | |
5544 | +** The value returned by sqlite3_backup_finish is [SQLITE_OK] if no error | |
5545 | +** occurred, regardless or whether or not sqlite3_backup_step() was called | |
5546 | +** a sufficient number of times to complete the backup operation. Or, if | |
5547 | +** an out-of-memory condition or IO error occured during a call to | |
5548 | +** sqlite3_backup_step() then [SQLITE_NOMEM] or an | |
5549 | +** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] error code | |
5550 | +** is returned. In this case the error code and an error message are | |
5551 | +** written to the destination [database connection]. | |
5552 | +** | |
5553 | +** A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step() is | |
5554 | +** not a permanent error and does not affect the return value of | |
5555 | +** sqlite3_backup_finish(). | |
5556 | +** | |
5557 | +** <b>sqlite3_backup_remaining(), sqlite3_backup_pagecount()</b> | |
5558 | +** | |
5559 | +** Each call to sqlite3_backup_step() sets two values stored internally | |
5560 | +** by an [sqlite3_backup] object. The number of pages still to be backed | |
5561 | +** up, which may be queried by sqlite3_backup_remaining(), and the total | |
5562 | +** number of pages in the source database file, which may be queried by | |
5563 | +** sqlite3_backup_pagecount(). | |
5564 | +** | |
5565 | +** The values returned by these functions are only updated by | |
5566 | +** sqlite3_backup_step(). If the source database is modified during a backup | |
5567 | +** operation, then the values are not updated to account for any extra | |
5568 | +** pages that need to be updated or the size of the source database file | |
5569 | +** changing. | |
5570 | +** | |
5571 | +** <b>Concurrent Usage of Database Handles</b> | |
5572 | +** | |
5573 | +** The source [database connection] may be used by the application for other | |
5574 | +** purposes while a backup operation is underway or being initialized. | |
5575 | +** If SQLite is compiled and configured to support threadsafe database | |
5576 | +** connections, then the source database connection may be used concurrently | |
5577 | +** from within other threads. | |
5578 | +** | |
5579 | +** However, the application must guarantee that the destination database | |
5580 | +** connection handle is not passed to any other API (by any thread) after | |
5581 | +** sqlite3_backup_init() is called and before the corresponding call to | |
5582 | +** sqlite3_backup_finish(). Unfortunately SQLite does not currently check | |
5583 | +** for this, if the application does use the destination [database connection] | |
5584 | +** for some other purpose during a backup operation, things may appear to | |
5585 | +** work correctly but in fact be subtly malfunctioning. Use of the | |
5586 | +** destination database connection while a backup is in progress might | |
5587 | +** also cause a mutex deadlock. | |
5588 | +** | |
5589 | +** Furthermore, if running in [shared cache mode], the application must | |
5590 | +** guarantee that the shared cache used by the destination database | |
5591 | +** is not accessed while the backup is running. In practice this means | |
5592 | +** that the application must guarantee that the file-system file being | |
5593 | +** backed up to is not accessed by any connection within the process, | |
5594 | +** not just the specific connection that was passed to sqlite3_backup_init(). | |
5595 | +** | |
5596 | +** The [sqlite3_backup] object itself is partially threadsafe. Multiple | |
5597 | +** threads may safely make multiple concurrent calls to sqlite3_backup_step(). | |
5598 | +** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount() | |
5599 | +** APIs are not strictly speaking threadsafe. If they are invoked at the | |
5600 | +** same time as another thread is invoking sqlite3_backup_step() it is | |
5601 | +** possible that they return invalid values. | |
5602 | +*/ | |
5603 | +SQLITE_API sqlite3_backup *sqlite3_backup_init( | |
5604 | + sqlite3 *pDest, /* Destination database handle */ | |
5605 | + const char *zDestName, /* Destination database name */ | |
5606 | + sqlite3 *pSource, /* Source database handle */ | |
5607 | + const char *zSourceName /* Source database name */ | |
5608 | +); | |
5609 | +SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage); | |
5610 | +SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p); | |
5611 | +SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p); | |
5612 | +SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p); | |
5613 | + | |
5614 | +/* | |
5615 | +** CAPI3REF: Unlock Notification | |
5616 | +** EXPERIMENTAL | |
5617 | +** | |
5618 | +** When running in shared-cache mode, a database operation may fail with | |
5619 | +** an [SQLITE_LOCKED] error if the required locks on the shared-cache or | |
5620 | +** individual tables within the shared-cache cannot be obtained. See | |
5621 | +** [SQLite Shared-Cache Mode] for a description of shared-cache locking. | |
5622 | +** This API may be used to register a callback that SQLite will invoke | |
5623 | +** when the connection currently holding the required lock relinquishes it. | |
5624 | +** This API is only available if the library was compiled with the | |
5625 | +** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined. | |
5626 | +** | |
5627 | +** See Also: [Using the SQLite Unlock Notification Feature]. | |
5628 | +** | |
5629 | +** Shared-cache locks are released when a database connection concludes | |
5630 | +** its current transaction, either by committing it or rolling it back. | |
5631 | +** | |
5632 | +** When a connection (known as the blocked connection) fails to obtain a | |
5633 | +** shared-cache lock and SQLITE_LOCKED is returned to the caller, the | |
5634 | +** identity of the database connection (the blocking connection) that | |
5635 | +** has locked the required resource is stored internally. After an | |
5636 | +** application receives an SQLITE_LOCKED error, it may call the | |
5637 | +** sqlite3_unlock_notify() method with the blocked connection handle as | |
5638 | +** the first argument to register for a callback that will be invoked | |
5639 | +** when the blocking connections current transaction is concluded. The | |
5640 | +** callback is invoked from within the [sqlite3_step] or [sqlite3_close] | |
5641 | +** call that concludes the blocking connections transaction. | |
5642 | +** | |
5643 | +** If sqlite3_unlock_notify() is called in a multi-threaded application, | |
5644 | +** there is a chance that the blocking connection will have already | |
5645 | +** concluded its transaction by the time sqlite3_unlock_notify() is invoked. | |
5646 | +** If this happens, then the specified callback is invoked immediately, | |
5647 | +** from within the call to sqlite3_unlock_notify(). | |
5648 | +** | |
5649 | +** If the blocked connection is attempting to obtain a write-lock on a | |
5650 | +** shared-cache table, and more than one other connection currently holds | |
5651 | +** a read-lock on the same table, then SQLite arbitrarily selects one of | |
5652 | +** the other connections to use as the blocking connection. | |
5653 | +** | |
5654 | +** There may be at most one unlock-notify callback registered by a | |
5655 | +** blocked connection. If sqlite3_unlock_notify() is called when the | |
5656 | +** blocked connection already has a registered unlock-notify callback, | |
5657 | +** then the new callback replaces the old. If sqlite3_unlock_notify() is | |
5658 | +** called with a NULL pointer as its second argument, then any existing | |
5659 | +** unlock-notify callback is cancelled. The blocked connections | |
5660 | +** unlock-notify callback may also be canceled by closing the blocked | |
5661 | +** connection using [sqlite3_close()]. | |
5662 | +** | |
5663 | +** The unlock-notify callback is not reentrant. If an application invokes | |
5664 | +** any sqlite3_xxx API functions from within an unlock-notify callback, a | |
5665 | +** crash or deadlock may be the result. | |
5666 | +** | |
5667 | +** Unless deadlock is detected (see below), sqlite3_unlock_notify() always | |
5668 | +** returns SQLITE_OK. | |
5669 | +** | |
5670 | +** <b>Callback Invocation Details</b> | |
5671 | +** | |
5672 | +** When an unlock-notify callback is registered, the application provides a | |
5673 | +** single void* pointer that is passed to the callback when it is invoked. | |
5674 | +** However, the signature of the callback function allows SQLite to pass | |
5675 | +** it an array of void* context pointers. The first argument passed to | |
5676 | +** an unlock-notify callback is a pointer to an array of void* pointers, | |
5677 | +** and the second is the number of entries in the array. | |
5678 | +** | |
5679 | +** When a blocking connections transaction is concluded, there may be | |
5680 | +** more than one blocked connection that has registered for an unlock-notify | |
5681 | +** callback. If two or more such blocked connections have specified the | |
5682 | +** same callback function, then instead of invoking the callback function | |
5683 | +** multiple times, it is invoked once with the set of void* context pointers | |
5684 | +** specified by the blocked connections bundled together into an array. | |
5685 | +** This gives the application an opportunity to prioritize any actions | |
5686 | +** related to the set of unblocked database connections. | |
5687 | +** | |
5688 | +** <b>Deadlock Detection</b> | |
5689 | +** | |
5690 | +** Assuming that after registering for an unlock-notify callback a | |
5691 | +** database waits for the callback to be issued before taking any further | |
5692 | +** action (a reasonable assumption), then using this API may cause the | |
5693 | +** application to deadlock. For example, if connection X is waiting for | |
5694 | +** connection Y's transaction to be concluded, and similarly connection | |
5695 | +** Y is waiting on connection X's transaction, then neither connection | |
5696 | +** will proceed and the system may remain deadlocked indefinitely. | |
5697 | +** | |
5698 | +** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock | |
5699 | +** detection. If a given call to sqlite3_unlock_notify() would put the | |
5700 | +** system in a deadlocked state, then SQLITE_LOCKED is returned and no | |
5701 | +** unlock-notify callback is registered. The system is said to be in | |
5702 | +** a deadlocked state if connection A has registered for an unlock-notify | |
5703 | +** callback on the conclusion of connection B's transaction, and connection | |
5704 | +** B has itself registered for an unlock-notify callback when connection | |
5705 | +** A's transaction is concluded. Indirect deadlock is also detected, so | |
5706 | +** the system is also considered to be deadlocked if connection B has | |
5707 | +** registered for an unlock-notify callback on the conclusion of connection | |
5708 | +** C's transaction, where connection C is waiting on connection A. Any | |
5709 | +** number of levels of indirection are allowed. | |
5710 | +** | |
5711 | +** <b>The "DROP TABLE" Exception</b> | |
5712 | +** | |
5713 | +** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost | |
5714 | +** always appropriate to call sqlite3_unlock_notify(). There is however, | |
5715 | +** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement, | |
5716 | +** SQLite checks if there are any currently executing SELECT statements | |
5717 | +** that belong to the same connection. If there are, SQLITE_LOCKED is | |
5718 | +** returned. In this case there is no "blocking connection", so invoking | |
5719 | +** sqlite3_unlock_notify() results in the unlock-notify callback being | |
5720 | +** invoked immediately. If the application then re-attempts the "DROP TABLE" | |
5721 | +** or "DROP INDEX" query, an infinite loop might be the result. | |
5722 | +** | |
5723 | +** One way around this problem is to check the extended error code returned | |
5724 | +** by an sqlite3_step() call. If there is a blocking connection, then the | |
5725 | +** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in | |
5726 | +** the special "DROP TABLE/INDEX" case, the extended error code is just | |
5727 | +** SQLITE_LOCKED. | |
5728 | +*/ | |
5729 | +SQLITE_API int sqlite3_unlock_notify( | |
5730 | + sqlite3 *pBlocked, /* Waiting connection */ | |
5731 | + void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */ | |
5732 | + void *pNotifyArg /* Argument to pass to xNotify */ | |
5733 | +); | |
5734 | + | |
5735 | + | |
5736 | +/* | |
5737 | +** CAPI3REF: String Comparison | |
5738 | +** EXPERIMENTAL | |
5739 | +** | |
5740 | +** The [sqlite3_strnicmp()] API allows applications and extensions to | |
5741 | +** compare the contents of two buffers containing UTF-8 strings in a | |
5742 | +** case-indendent fashion, using the same definition of case independence | |
5743 | +** that SQLite uses internally when comparing identifiers. | |
5744 | +*/ | |
5745 | +SQLITE_API int sqlite3_strnicmp(const char *, const char *, int); | |
2690 | 5746 | |
2691 | 5747 | /* |
2692 | 5748 | ** Undo the hack that converts floating point types to integer for |
@@ -2700,3 +5756,4 @@ int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); | ||
2700 | 5756 | } /* End of the 'extern "C"' block */ |
2701 | 5757 | #endif |
2702 | 5758 | #endif |
5759 | + |