Merge Chromium + Blink git repositories
[chromium-blink-merge.git] / third_party / sqlite / sqlite-src-3080704 / src / test_quota.h
blobc17e15adca19233249fa43791037b4ec6bd47441
1 /*
2 ** 2011 December 1
3 **
4 ** The author disclaims copyright to this source code. In place of
5 ** a legal notice, here is a blessing:
6 **
7 ** May you do good and not evil.
8 ** May you find forgiveness for yourself and forgive others.
9 ** May you share freely, never taking more than you give.
11 *************************************************************************
13 ** This file contains the interface definition for the quota a VFS shim.
15 ** This particular shim enforces a quota system on files. One or more
16 ** database files are in a "quota group" that is defined by a GLOB
17 ** pattern. A quota is set for the combined size of all files in the
18 ** the group. A quota of zero means "no limit". If the total size
19 ** of all files in the quota group is greater than the limit, then
20 ** write requests that attempt to enlarge a file fail with SQLITE_FULL.
22 ** However, before returning SQLITE_FULL, the write requests invoke
23 ** a callback function that is configurable for each quota group.
24 ** This callback has the opportunity to enlarge the quota. If the
25 ** callback does enlarge the quota such that the total size of all
26 ** files within the group is less than the new quota, then the write
27 ** continues as if nothing had happened.
29 #ifndef _QUOTA_H_
30 #include "sqlite3.h"
31 #include <stdio.h>
32 #include <sys/types.h>
33 #include <sys/stat.h>
35 /* Make this callable from C++ */
36 #ifdef __cplusplus
37 extern "C" {
38 #endif
41 ** Initialize the quota VFS shim. Use the VFS named zOrigVfsName
42 ** as the VFS that does the actual work. Use the default if
43 ** zOrigVfsName==NULL.
45 ** The quota VFS shim is named "quota". It will become the default
46 ** VFS if makeDefault is non-zero.
48 ** THIS ROUTINE IS NOT THREADSAFE. Call this routine exactly once
49 ** during start-up.
51 int sqlite3_quota_initialize(const char *zOrigVfsName, int makeDefault);
54 ** Shutdown the quota system.
56 ** All SQLite database connections must be closed before calling this
57 ** routine.
59 ** THIS ROUTINE IS NOT THREADSAFE. Call this routine exactly once while
60 ** shutting down in order to free all remaining quota groups.
62 int sqlite3_quota_shutdown(void);
65 ** Create or destroy a quota group.
67 ** The quota group is defined by the zPattern. When calling this routine
68 ** with a zPattern for a quota group that already exists, this routine
69 ** merely updates the iLimit, xCallback, and pArg values for that quota
70 ** group. If zPattern is new, then a new quota group is created.
72 ** The zPattern is always compared against the full pathname of the file.
73 ** Even if APIs are called with relative pathnames, SQLite converts the
74 ** name to a full pathname before comparing it against zPattern. zPattern
75 ** is a glob pattern with the following matching rules:
77 ** '*' Matches any sequence of zero or more characters.
79 ** '?' Matches exactly one character.
81 ** [...] Matches one character from the enclosed list of
82 ** characters. "]" can be part of the list if it is
83 ** the first character. Within the list "X-Y" matches
84 ** characters X or Y or any character in between the
85 ** two. Ex: "[0-9]" matches any digit.
87 ** [^...] Matches one character not in the enclosed list.
89 ** / Matches either / or \. This allows glob patterns
90 ** containing / to work on both unix and windows.
92 ** Note that, unlike unix shell globbing, the directory separator "/"
93 ** can match a wildcard. So, for example, the pattern "/abc/xyz/" "*"
94 ** matches any files anywhere in the directory hierarchy beneath
95 ** /abc/xyz.
97 ** The glob algorithm works on bytes. Multi-byte UTF8 characters are
98 ** matched as if each byte were a separate character.
100 ** If the iLimit for a quota group is set to zero, then the quota group
101 ** is disabled and will be deleted when the last database connection using
102 ** the quota group is closed.
104 ** Calling this routine on a zPattern that does not exist and with a
105 ** zero iLimit is a no-op.
107 ** A quota group must exist with a non-zero iLimit prior to opening
108 ** database connections if those connections are to participate in the
109 ** quota group. Creating a quota group does not affect database connections
110 ** that are already open.
112 ** The patterns that define the various quota groups should be distinct.
113 ** If the same filename matches more than one quota group pattern, then
114 ** the behavior of this package is undefined.
116 int sqlite3_quota_set(
117 const char *zPattern, /* The filename pattern */
118 sqlite3_int64 iLimit, /* New quota to set for this quota group */
119 void (*xCallback)( /* Callback invoked when going over quota */
120 const char *zFilename, /* Name of file whose size increases */
121 sqlite3_int64 *piLimit, /* IN/OUT: The current limit */
122 sqlite3_int64 iSize, /* Total size of all files in the group */
123 void *pArg /* Client data */
125 void *pArg, /* client data passed thru to callback */
126 void (*xDestroy)(void*) /* Optional destructor for pArg */
130 ** Bring the named file under quota management, assuming its name matches
131 ** the glob pattern of some quota group. Or if it is already under
132 ** management, update its size. If zFilename does not match the glob
133 ** pattern of any quota group, this routine is a no-op.
135 int sqlite3_quota_file(const char *zFilename);
138 ** The following object serves the same role as FILE in the standard C
139 ** library. It represents an open connection to a file on disk for I/O.
141 ** A single quota_FILE should not be used by two or more threads at the
142 ** same time. Multiple threads can be using different quota_FILE objects
143 ** simultaneously, but not the same quota_FILE object.
145 typedef struct quota_FILE quota_FILE;
148 ** Create a new quota_FILE object used to read and/or write to the
149 ** file zFilename. The zMode parameter is as with standard library zMode.
151 quota_FILE *sqlite3_quota_fopen(const char *zFilename, const char *zMode);
154 ** Perform I/O against a quota_FILE object. When doing writes, the
155 ** quota mechanism may result in a short write, in order to prevent
156 ** the sum of sizes of all files from going over quota.
158 size_t sqlite3_quota_fread(void*, size_t, size_t, quota_FILE*);
159 size_t sqlite3_quota_fwrite(const void*, size_t, size_t, quota_FILE*);
162 ** Flush all written content held in memory buffers out to disk.
163 ** This is the equivalent of fflush() in the standard library.
165 ** If the hardSync parameter is true (non-zero) then this routine
166 ** also forces OS buffers to disk - the equivalent of fsync().
168 ** This routine return zero on success and non-zero if something goes
169 ** wrong.
171 int sqlite3_quota_fflush(quota_FILE*, int hardSync);
174 ** Close a quota_FILE object and free all associated resources. The
175 ** file remains under quota management.
177 int sqlite3_quota_fclose(quota_FILE*);
180 ** Move the read/write pointer for a quota_FILE object. Or tell the
181 ** current location of the read/write pointer.
183 int sqlite3_quota_fseek(quota_FILE*, long, int);
184 void sqlite3_quota_rewind(quota_FILE*);
185 long sqlite3_quota_ftell(quota_FILE*);
188 ** Test the error indicator for the given file.
190 ** Return non-zero if the error indicator is set.
192 int sqlite3_quota_ferror(quota_FILE*);
195 ** Truncate a file previously opened by sqlite3_quota_fopen(). Return
196 ** zero on success and non-zero on any kind of failure.
198 ** The newSize argument must be less than or equal to the current file size.
199 ** Any attempt to "truncate" a file to a larger size results in
200 ** undefined behavior.
202 int sqlite3_quota_ftruncate(quota_FILE*, sqlite3_int64 newSize);
205 ** Return the last modification time of the opened file, in seconds
206 ** since 1970.
208 int sqlite3_quota_file_mtime(quota_FILE*, time_t *pTime);
211 ** Return the size of the file as it is known to the quota system.
213 ** This size might be different from the true size of the file on
214 ** disk if some outside process has modified the file without using the
215 ** quota mechanism, or if calls to sqlite3_quota_fwrite() have occurred
216 ** which have increased the file size, but those writes have not yet been
217 ** forced to disk using sqlite3_quota_fflush().
219 ** Return -1 if the file is not participating in quota management.
221 sqlite3_int64 sqlite3_quota_file_size(quota_FILE*);
224 ** Return the true size of the file.
226 ** The true size should be the same as the size of the file as known
227 ** to the quota system, however the sizes might be different if the
228 ** file has been extended or truncated via some outside process or if
229 ** pending writes have not yet been flushed to disk.
231 ** Return -1 if the file does not exist or if the size of the file
232 ** cannot be determined for some reason.
234 sqlite3_int64 sqlite3_quota_file_truesize(quota_FILE*);
237 ** Determine the amount of data in bytes available for reading
238 ** in the given file.
240 ** Return -1 if the amount cannot be determined for some reason.
242 long sqlite3_quota_file_available(quota_FILE*);
245 ** Delete a file from the disk, if that file is under quota management.
246 ** Adjust quotas accordingly.
248 ** If zFilename is the name of a directory that matches one of the
249 ** quota glob patterns, then all files under quota management that
250 ** are contained within that directory are deleted.
252 ** A standard SQLite result code is returned (SQLITE_OK, SQLITE_NOMEM, etc.)
253 ** When deleting a directory of files, if the deletion of any one
254 ** file fails (for example due to an I/O error), then this routine
255 ** returns immediately, with the error code, and does not try to
256 ** delete any of the other files in the specified directory.
258 ** All files are removed from quota management and deleted from disk.
259 ** However, no attempt is made to remove empty directories.
261 ** This routine is a no-op for files that are not under quota management.
263 int sqlite3_quota_remove(const char *zFilename);
265 #ifdef __cplusplus
266 } /* end of the 'extern "C"' block */
267 #endif
268 #endif /* _QUOTA_H_ */