~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 File Virtual Methods Object</h2><blockquote><pre>typedef struct sqlite3_io_methods sqlite3_io_methods;

121

struct sqlite3_io_methods {

122

int iVersion;

123

int (*xClose)(sqlite3_file*);

124

int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);

125

int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);

126

int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);

127

int (*xSync)(sqlite3_file*, int flags);

128

int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);

129

int (*xLock)(sqlite3_file*, int);

130

int (*xUnlock)(sqlite3_file*, int);

131

int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);

132

int (*xFileControl)(sqlite3_file*, int op, void *pArg);

133

int (*xSectorSize)(sqlite3_file*);

134

int (*xDeviceCharacteristics)(sqlite3_file*);

135

/* Methods above are valid for version 1 */

136

int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);

137

int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);

138

void (*xShmBarrier)(sqlite3_file*);

139

int (*xShmUnmap)(sqlite3_file*, int deleteFlag);

140

/* Methods above are valid for version 2 */

141

/* Additional methods may be added in future releases */

142

};

143

</pre></blockquote><p>

144

Every file opened by the <a href="../c3ref/vfs.html#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> method populates an

145

<a href="../c3ref/file.html">sqlite3_file</a> object (or, more commonly, a subclass of the

146

<a href="../c3ref/file.html">sqlite3_file</a> object) with a pointer to an instance of this object.

147

This object defines the methods used to perform various operations

148

against the open file represented by the <a href="../c3ref/file.html">sqlite3_file</a> object.</p>

149

150

<p>If the <a href="../c3ref/vfs.html#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> method sets the sqlite3_file.pMethods element

151

to a non-NULL pointer, then the sqlite3_io_methods.xClose method

152

may be invoked even if the <a href="../c3ref/vfs.html#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> reported that it failed. The

153

only way to prevent a call to xClose following a failed <a href="../c3ref/vfs.html#sqlite3vfsxopen">sqlite3_vfs.xOpen</a>

154

is for the <a href="../c3ref/vfs.html#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> to set the sqlite3_file.pMethods element

155

to NULL.</p>

156

157

<p>The flags argument to xSync may be one of <a href="../c3ref/c_sync_dataonly.html">SQLITE_SYNC_NORMAL</a> or

158

<a href="../c3ref/c_sync_dataonly.html">SQLITE_SYNC_FULL</a>. The first choice is the normal fsync().

159

The second choice is a Mac OS X style fullsync. The <a href="../c3ref/c_sync_dataonly.html">SQLITE_SYNC_DATAONLY</a>

160

flag may be ORed in to indicate that only the data of the file

161

and not its inode needs to be synced.</p>

162

163

<p>The integer values to xLock() and xUnlock() are one of

164

<ul>

165

<li> <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_NONE</a>,

166

<li> <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a>,

167

<li> <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_RESERVED</a>,

168

<li> <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_PENDING</a>, or

169

<li> <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_EXCLUSIVE</a>.

170

</ul>

171

xLock() increases the lock. xUnlock() decreases the lock.

172

The xCheckReservedLock() method checks whether any database connection,

173

either in this process or in some other process, is holding a RESERVED,

174

PENDING, or EXCLUSIVE lock on the file. It returns true

175

if such a lock exists and false otherwise.</p>

176

177

<p>The xFileControl() method is a generic interface that allows custom

178

VFS implementations to directly control an open file using the

179

<a href="../c3ref/file_control.html">sqlite3_file_control()</a> interface. The second "op" argument is an

180

integer opcode. The third argument is a generic pointer intended to

181

point to a structure that may contain arguments or space in which to

182

write return values. Potential uses for xFileControl() might be

183

functions to enable blocking locks with timeouts, to change the

184

locking strategy (for example to use dot-file locks), to inquire

185

about the status of a lock, or to break stale locks. The SQLite

186

core reserves all opcodes less than 100 for its own use.

187

A <a href="../c3ref/c_fcntl_chunk_size.html">list of opcodes</a> less than 100 is available.

188

Applications that define a custom xFileControl method should use opcodes

189

greater than 100 to avoid conflicts. VFS implementations should

190

return <a href="../c3ref/c_abort.html">SQLITE_NOTFOUND</a> for file control opcodes that they do not

191

recognize.</p>

192

193

<p>The xSectorSize() method returns the sector size of the

194

device that underlies the file. The sector size is the

195

minimum write that can be performed without disturbing

196

other bytes in the file. The xDeviceCharacteristics()

197

method returns a bit vector describing behaviors of the

198

underlying device:</p>

199

200

<p><ul>

201

<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC</a>

202

<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC512</a>

203

<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC1K</a>

204

<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC2K</a>

205

<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC4K</a>

206

<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC8K</a>

207

<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC16K</a>

208

<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC32K</a>

209

<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC64K</a>

210

<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SAFE_APPEND</a>

211

<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SEQUENTIAL</a>

212

</ul></p>

213

214

<p>The SQLITE_IOCAP_ATOMIC property means that all writes of

215

any size are atomic. The SQLITE_IOCAP_ATOMICnnn values

216

mean that writes of blocks that are nnn bytes in size and

217

are aligned to an address which is an integer multiple of

218

nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means

219

that when data is appended to a file, the data is appended

220

first then the size of the file is extended, never the other

221

way around. The SQLITE_IOCAP_SEQUENTIAL property means that

222

information is written to disk in the same order as calls

223

to xWrite().</p>

224

225

<p>If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill

226

in the unread portions of the buffer with zeros. A VFS that

227

fails to zero-fill short reads might seem to work. However,

228

failure to zero-fill short reads will eventually lead to

229

database corruption.

230

</p><p>See also lists of

231

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

232

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

233

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