~ubuntu-branches/ubuntu/wily/sqlite3/wily

onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">

112

113

</form>

114

</div>

115

</table>

116

</div></div></div></div>

117

</td></tr></table>

118

119

120

<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>OS Interface Object</h2><blockquote><pre>typedef struct sqlite3_vfs sqlite3_vfs;

121

typedef void (*sqlite3_syscall_ptr)(void);

122

struct sqlite3_vfs {

123

int iVersion; /* Structure version number (currently 3) */

124

int szOsFile; /* Size of subclassed sqlite3_file */

125

int mxPathname; /* Maximum file pathname length */

126

sqlite3_vfs *pNext; /* Next registered VFS */

127

const char *zName; /* Name of this virtual file system */

128

void *pAppData; /* Pointer to application-specific data */

129

int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,

130

int flags, int *pOutFlags);

131

int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);

132

int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);

133

int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);

134

void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);

135

void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);

136

void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);

137

void (*xDlClose)(sqlite3_vfs*, void*);

138

int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);

139

int (*xSleep)(sqlite3_vfs*, int microseconds);

140

int (*xCurrentTime)(sqlite3_vfs*, double*);

141

int (*xGetLastError)(sqlite3_vfs*, int, char *);

142

143

** The methods above are in version 1 of the sqlite_vfs object

144

** definition. Those that follow are added in version 2 or later

145

146

int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);

147

148

** The methods above are in versions 1 and 2 of the sqlite_vfs object.

149

** Those below are for version 3 and greater.

150

151

int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);

152

sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);

153

const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);

154

155

** The methods above are in versions 1 through 3 of the sqlite_vfs object.

156

** New fields may be appended in figure versions. The iVersion

157

** value will increment whenever this happens.

158

159

};

160

</pre></blockquote><p>

161

An instance of the sqlite3_vfs object defines the interface between

162

the SQLite core and the underlying operating system. The "vfs"

163

in the name of the object stands for "virtual file system". See

164

the <a href="../vfs.html">VFS documentation</a> for further information.</p>

165

166

<p>The value of the iVersion field is initially 1 but may be larger in

167

future versions of SQLite. Additional fields may be appended to this

168

object when the iVersion value is increased. Note that the structure

169

of the sqlite3_vfs object changes in the transaction between

170

SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not

171

modified.</p>

172

173

<p>The szOsFile field is the size of the subclassed <a href="../c3ref/file.html">sqlite3_file</a>

174

structure used by this VFS. mxPathname is the maximum length of

175

a pathname in this VFS.</p>

176

177

<p>Registered sqlite3_vfs objects are kept on a linked list formed by

178

the pNext pointer. The <a href="../c3ref/vfs_find.html">sqlite3_vfs_register()</a>

179

and <a href="../c3ref/vfs_find.html">sqlite3_vfs_unregister()</a> interfaces manage this list

180

in a thread-safe way. The <a href="../c3ref/vfs_find.html">sqlite3_vfs_find()</a> interface

181

searches the list. Neither the application code nor the VFS

182

implementation should use the pNext pointer.</p>

183

184

<p>The pNext field is the only field in the sqlite3_vfs

185

structure that SQLite will ever modify. SQLite will only access

186

or modify this field while holding a particular static mutex.

187

The application should never modify anything within the sqlite3_vfs

188

object once the object has been registered.</p>

189

190

<p>The zName field holds the name of the VFS module. The name must

191

be unique across all VFS modules.</p>

192

193

194

195

SQLite guarantees that the zFilename parameter to xOpen

196

is either a NULL pointer or string obtained

197

from xFullPathname() with an optional suffix added.

198

If a suffix is added to the zFilename parameter, it will

199

consist of a single "-" character followed by no more than

200

11 alphanumeric and/or "-" characters.

201

SQLite further guarantees that

202

the string will be valid and unchanged until xClose() is

203

called. Because of the previous sentence,

204

the <a href="../c3ref/file.html">sqlite3_file</a> can safely store a pointer to the

205

filename if it needs to remember the filename for some reason.

206

If the zFilename parameter to xOpen is a NULL pointer then xOpen

207

must invent its own temporary name for the file. Whenever the

208

xFilename parameter is NULL it will also be the case that the

209

flags parameter will include <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_DELETEONCLOSE</a>.</p>

210

211

<p>The flags argument to xOpen() includes all bits set in

212

the flags argument to <a href="../c3ref/open.html">sqlite3_open_v2()</a>. Or if <a href="../c3ref/open.html">sqlite3_open()</a>

213

or <a href="../c3ref/open.html">sqlite3_open16()</a> is used, then flags includes at least

214

<a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READWRITE</a> | <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_CREATE</a>.

215

If xOpen() opens a file read-only then it sets *pOutFlags to

216

include <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READONLY</a>. Other bits in *pOutFlags may be set.</p>

217

218

<p>SQLite will also add one of the following flags to the xOpen()

219

call, depending on the object being opened:</p>

220

221

<p><ul>

222

<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_MAIN_DB</a>

223

<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_MAIN_JOURNAL</a>

224

<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_TEMP_DB</a>

225

<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_TEMP_JOURNAL</a>

226

<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_TRANSIENT_DB</a>

227

<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_SUBJOURNAL</a>

228

<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_MASTER_JOURNAL</a>

229

<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_WAL</a>

230

</ul></p>

231

232

<p>The file I/O implementation can use the object type flags to

233

change the way it deals with files. For example, an application

234

that does not care about crash recovery or rollback might make

235

the open of a journal file a no-op. Writes to this journal would

236

also be no-ops, and any attempt to read the journal would return

237

SQLITE_IOERR. Or the implementation might recognize that a database

238

file will be doing page-aligned sector reads and writes in a random

239

order and set up its I/O subsystem accordingly.</p>

240

241

<p>SQLite might also add one of the following flags to the xOpen method:</p>

242

243

<p><ul>

244

<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_DELETEONCLOSE</a>

245

<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_EXCLUSIVE</a>

246

</ul></p>

247

248

<p>The <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_DELETEONCLOSE</a> flag means the file should be

249

deleted when it is closed. The <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_DELETEONCLOSE</a>

250

will be set for TEMP databases and their journals, transient

251

databases, and subjournals.</p>

252

253

<p>The <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_EXCLUSIVE</a> flag is always used in conjunction

254

with the <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_CREATE</a> flag, which are both directly

255

analogous to the O_EXCL and O_CREAT flags of the POSIX open()

256

API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the

257

SQLITE_OPEN_CREATE, is used to indicate that file should always

258

be created, and that it is an error if it already exists.

259

It is <i>not</i> used to indicate the file should be opened

260

for exclusive access.</p>

261

262

<p>At least szOsFile bytes of memory are allocated by SQLite

263

to hold the <a href="../c3ref/file.html">sqlite3_file</a> structure passed as the third

264

argument to xOpen. The xOpen method does not have to

265

allocate the structure; it should just fill it in. Note that

266

the xOpen method must set the sqlite3_file.pMethods to either

267

a valid <a href="../c3ref/io_methods.html">sqlite3_io_methods</a> object or to NULL. xOpen must do

268

this even if the open fails. SQLite expects that the sqlite3_file.pMethods

269

element will be valid after xOpen returns regardless of the success

270

or failure of the xOpen call.</p>

271

272

273

274

The flags argument to xAccess() may be <a href="../c3ref/c_access_exists.html">SQLITE_ACCESS_EXISTS</a>

275

to test for the existence of a file, or <a href="../c3ref/c_access_exists.html">SQLITE_ACCESS_READWRITE</a> to

276

test whether a file is readable and writable, or <a href="../c3ref/c_access_exists.html">SQLITE_ACCESS_READ</a>

277

to test whether a file is at least readable. The file can be a

278

directory.</p>

279

280

<p>SQLite will always allocate at least mxPathname+1 bytes for the

281

output buffer xFullPathname. The exact size of the output buffer

282

is also passed as a parameter to both methods. If the output buffer

283

is not large enough, <a href="../c3ref/c_abort.html">SQLITE_CANTOPEN</a> should be returned. Since this is

284

handled as a fatal error by SQLite, vfs implementations should endeavor

285

to prevent this by setting mxPathname to a sufficiently large value.</p>

286

287

<p>The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()

288

interfaces are not strictly a part of the filesystem, but they are

289

included in the VFS structure for completeness.

290

The xRandomness() function attempts to return nBytes bytes

291

of good-quality randomness into zOut. The return value is

292

the actual number of bytes of randomness obtained.

293

The xSleep() method causes the calling thread to sleep for at

294

least the number of microseconds given. The xCurrentTime()

295

method returns a Julian Day Number for the current date and time as

296

a floating point value.

297

The xCurrentTimeInt64() method returns, as an integer, the Julian

298

Day Number multiplied by 86400000 (the number of milliseconds in

299

a 24-hour day).

300

SQLite will use the xCurrentTimeInt64() method to get the current

301

date and time if that method is available (if iVersion is 2 or

302

greater and the function pointer is not NULL) and will fall back

303

to xCurrentTime() if xCurrentTimeInt64() is unavailable.</p>

304

305

<p>The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces

306

are not used by the SQLite core. These optional interfaces are provided

307

by some VFSes to facilitate testing of the VFS code. By overriding

308

system calls with functions under its control, a test program can

309

simulate faults and error conditions that would otherwise be difficult

310

or impossible to induce. The set of system calls that can be overridden

311

varies from one VFS to another, and from one version of the same VFS to the

312

next. Applications that use these interfaces must be prepared for any

313

or all of these interfaces to be NULL or for their behavior to change

314

from one release to the next. Applications must not attempt to access

315

any of these methods if the iVersion of the VFS is less than 3.

316

</p><p>See also lists of

317

<a href="objlist.html">Objects</a>,

318

<a href="constlist.html">Constants</a>, and

319

<a href="funclist.html">Functions</a>.</p>