Annotation of embedaddon/sqlite3/src/test_quota.h, revision 1.1.1.1
1.1 misho 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.
10: **
11: *************************************************************************
12: **
13: ** This file contains the interface definition for the quota a VFS shim.
14: **
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.
21: **
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.
28: */
29: #ifndef _QUOTA_H_
30: #include "sqlite3.h"
31: #include <stdio.h>
32:
33: /* Make this callable from C++ */
34: #ifdef __cplusplus
35: extern "C" {
36: #endif
37:
38: /*
39: ** Initialize the quota VFS shim. Use the VFS named zOrigVfsName
40: ** as the VFS that does the actual work. Use the default if
41: ** zOrigVfsName==NULL.
42: **
43: ** The quota VFS shim is named "quota". It will become the default
44: ** VFS if makeDefault is non-zero.
45: **
46: ** THIS ROUTINE IS NOT THREADSAFE. Call this routine exactly once
47: ** during start-up.
48: */
49: int sqlite3_quota_initialize(const char *zOrigVfsName, int makeDefault);
50:
51: /*
52: ** Shutdown the quota system.
53: **
54: ** All SQLite database connections must be closed before calling this
55: ** routine.
56: **
57: ** THIS ROUTINE IS NOT THREADSAFE. Call this routine exactly once while
58: ** shutting down in order to free all remaining quota groups.
59: */
60: int sqlite3_quota_shutdown(void);
61:
62: /*
63: ** Create or destroy a quota group.
64: **
65: ** The quota group is defined by the zPattern. When calling this routine
66: ** with a zPattern for a quota group that already exists, this routine
67: ** merely updates the iLimit, xCallback, and pArg values for that quota
68: ** group. If zPattern is new, then a new quota group is created.
69: **
70: ** The zPattern is always compared against the full pathname of the file.
71: ** Even if APIs are called with relative pathnames, SQLite converts the
72: ** name to a full pathname before comparing it against zPattern. zPattern
73: ** is a glob pattern with the following matching rules:
74: **
75: ** '*' Matches any sequence of zero or more characters.
76: **
77: ** '?' Matches exactly one character.
78: **
79: ** [...] Matches one character from the enclosed list of
80: ** characters. "]" can be part of the list if it is
81: ** the first character. Within the list "X-Y" matches
82: ** characters X or Y or any character in between the
83: ** two. Ex: "[0-9]" matches any digit.
84: **
85: ** [^...] Matches one character not in the enclosed list.
86: **
87: ** / Matches either / or \. This allows glob patterns
88: ** containing / to work on both unix and windows.
89: **
90: ** Note that, unlike unix shell globbing, the directory separator "/"
91: ** can match a wildcard. So, for example, the pattern "/abc/xyz/" "*"
92: ** matches any files anywhere in the directory hierarchy beneath
93: ** /abc/xyz.
94: **
95: ** The glob algorithm works on bytes. Multi-byte UTF8 characters are
96: ** matched as if each byte were a separate character.
97: **
98: ** If the iLimit for a quota group is set to zero, then the quota group
99: ** is disabled and will be deleted when the last database connection using
100: ** the quota group is closed.
101: **
102: ** Calling this routine on a zPattern that does not exist and with a
103: ** zero iLimit is a no-op.
104: **
105: ** A quota group must exist with a non-zero iLimit prior to opening
106: ** database connections if those connections are to participate in the
107: ** quota group. Creating a quota group does not affect database connections
108: ** that are already open.
109: **
110: ** The patterns that define the various quota groups should be distinct.
111: ** If the same filename matches more than one quota group pattern, then
112: ** the behavior of this package is undefined.
113: */
114: int sqlite3_quota_set(
115: const char *zPattern, /* The filename pattern */
116: sqlite3_int64 iLimit, /* New quota to set for this quota group */
117: void (*xCallback)( /* Callback invoked when going over quota */
118: const char *zFilename, /* Name of file whose size increases */
119: sqlite3_int64 *piLimit, /* IN/OUT: The current limit */
120: sqlite3_int64 iSize, /* Total size of all files in the group */
121: void *pArg /* Client data */
122: ),
123: void *pArg, /* client data passed thru to callback */
124: void (*xDestroy)(void*) /* Optional destructor for pArg */
125: );
126:
127: /*
128: ** Bring the named file under quota management, assuming its name matches
129: ** the glob pattern of some quota group. Or if it is already under
130: ** management, update its size. If zFilename does not match the glob
131: ** pattern of any quota group, this routine is a no-op.
132: */
133: int sqlite3_quota_file(const char *zFilename);
134:
135: /*
136: ** The following object serves the same role as FILE in the standard C
137: ** library. It represents an open connection to a file on disk for I/O.
138: **
139: ** A single quota_FILE should not be used by two or more threads at the
140: ** same time. Multiple threads can be using different quota_FILE objects
141: ** simultaneously, but not the same quota_FILE object.
142: */
143: typedef struct quota_FILE quota_FILE;
144:
145: /*
146: ** Create a new quota_FILE object used to read and/or write to the
147: ** file zFilename. The zMode parameter is as with standard library zMode.
148: */
149: quota_FILE *sqlite3_quota_fopen(const char *zFilename, const char *zMode);
150:
151: /*
152: ** Perform I/O against a quota_FILE object. When doing writes, the
153: ** quota mechanism may result in a short write, in order to prevent
154: ** the sum of sizes of all files from going over quota.
155: */
156: size_t sqlite3_quota_fread(void*, size_t, size_t, quota_FILE*);
157: size_t sqlite3_quota_fwrite(void*, size_t, size_t, quota_FILE*);
158:
159: /*
160: ** Flush all written content held in memory buffers out to disk.
161: ** This is the equivalent of fflush() in the standard library.
162: **
163: ** If the hardSync parameter is true (non-zero) then this routine
164: ** also forces OS buffers to disk - the equivalent of fsync().
165: **
166: ** This routine return zero on success and non-zero if something goes
167: ** wrong.
168: */
169: int sqlite3_quota_fflush(quota_FILE*, int hardSync);
170:
171: /*
172: ** Close a quota_FILE object and free all associated resources. The
173: ** file remains under quota management.
174: */
175: int sqlite3_quota_fclose(quota_FILE*);
176:
177: /*
178: ** Move the read/write pointer for a quota_FILE object. Or tell the
179: ** current location of the read/write pointer.
180: */
181: int sqlite3_quota_fseek(quota_FILE*, long, int);
182: void sqlite3_quota_rewind(quota_FILE*);
183: long sqlite3_quota_ftell(quota_FILE*);
184:
185: /*
186: ** Delete a file from the disk, if that file is under quota management.
187: ** Adjust quotas accordingly.
188: **
189: ** If zFilename is the name of a directory that matches one of the
190: ** quota glob patterns, then all files under quota management that
191: ** are contained within that directory are deleted.
192: **
193: ** A standard SQLite result code is returned (SQLITE_OK, SQLITE_NOMEM, etc.)
194: ** When deleting a directory of files, if the deletion of any one
195: ** file fails (for example due to an I/O error), then this routine
196: ** returns immediately, with the error code, and does not try to
197: ** delete any of the other files in the specified directory.
198: **
199: ** All files are removed from quota management and deleted from disk.
200: ** However, no attempt is made to remove empty directories.
201: **
202: ** This routine is a no-op for files that are not under quota management.
203: */
204: int sqlite3_quota_remove(const char *zFilename);
205:
206: #ifdef __cplusplus
207: } /* end of the 'extern "C"' block */
208: #endif
209: #endif /* _QUOTA_H_ */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to test_quota.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sqlite3 / src