1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
.Dd January 24, 2024
.Dt SQLITE3_IO_METHODS 3
.Os
.Sh NAME
.Nm sqlite3_io_methods ,
.Nm sqlite3_io_methods
.Nd OS interface file virtual methods object
.Sh SYNOPSIS
.In sqlite3.h
.Vt typedef struct sqlite3_io_methods sqlite3_io_methods;
.Vt struct sqlite3_io_methods ;
.Sh DESCRIPTION
Every file opened by the sqlite3_vfs.xOpen method
populates an sqlite3_file object (or, more commonly, a
subclass of the sqlite3_file object) with a pointer to
an instance of this object.
This object defines the methods used to perform various operations
against the open file represented by the sqlite3_file object.
.Pp
If the sqlite3_vfs.xOpen method sets the sqlite3_file.pMethods
element to a non-NULL pointer, then the sqlite3_io_methods.xClose method
may be invoked even if the sqlite3_vfs.xOpen reported
that it failed.
The only way to prevent a call to xClose following a failed sqlite3_vfs.xOpen
is for the sqlite3_vfs.xOpen to set the sqlite3_file.pMethods
element to NULL.
.Pp
The flags argument to xSync may be one of SQLITE_SYNC_NORMAL
or SQLITE_SYNC_FULL.
The first choice is the normal fsync().
The second choice is a Mac OS X style fullsync.
The SQLITE_SYNC_DATAONLY flag may be ORed in to
indicate that only the data of the file and not its inode needs to
be synced.
.Pp
The integer values to xLock() and xUnlock() are one of
.Bl -bullet
.It
SQLITE_LOCK_NONE,
.It
SQLITE_LOCK_SHARED,
.It
SQLITE_LOCK_RESERVED,
.It
SQLITE_LOCK_PENDING, or
.It
SQLITE_LOCK_EXCLUSIVE.
.El
.Pp
xLock() upgrades the database file lock.
In other words, xLock() moves the database file lock in the direction
NONE toward EXCLUSIVE.
The argument to xLock() is always on of SHARED, RESERVED, PENDING,
or EXCLUSIVE, never SQLITE_LOCK_NONE.
If the database file lock is already at or above the requested lock,
then the call to xLock() is a no-op.
xUnlock() downgrades the database file lock to either SHARED or NONE.
If the lock is already at or below the requested lock state, then the
call to xUnlock() is a no-op.
The xCheckReservedLock() method checks whether any database connection,
either in this process or in some other process, is holding a RESERVED,
PENDING, or EXCLUSIVE lock on the file.
It returns true if such a lock exists and false otherwise.
.Pp
The xFileControl() method is a generic interface that allows custom
VFS implementations to directly control an open file using the
.Fn sqlite3_file_control
interface.
The second "op" argument is an integer opcode.
The third argument is a generic pointer intended to point to a structure
that may contain arguments or space in which to write return values.
Potential uses for xFileControl() might be functions to enable blocking
locks with timeouts, to change the locking strategy (for example to
use dot-file locks), to inquire about the status of a lock, or to break
stale locks.
The SQLite core reserves all opcodes less than 100 for its own use.
A list of opcodes less than 100 is available.
Applications that define a custom xFileControl method should use opcodes
greater than 100 to avoid conflicts.
VFS implementations should return SQLITE_NOTFOUND for
file control opcodes that they do not recognize.
.Pp
The xSectorSize() method returns the sector size of the device that
underlies the file.
The sector size is the minimum write that can be performed without
disturbing other bytes in the file.
The xDeviceCharacteristics() method returns a bit vector describing
behaviors of the underlying device:
.Bl -bullet
.It
SQLITE_IOCAP_ATOMIC
.It
SQLITE_IOCAP_ATOMIC512
.It
SQLITE_IOCAP_ATOMIC1K
.It
SQLITE_IOCAP_ATOMIC2K
.It
SQLITE_IOCAP_ATOMIC4K
.It
SQLITE_IOCAP_ATOMIC8K
.It
SQLITE_IOCAP_ATOMIC16K
.It
SQLITE_IOCAP_ATOMIC32K
.It
SQLITE_IOCAP_ATOMIC64K
.It
SQLITE_IOCAP_SAFE_APPEND
.It
SQLITE_IOCAP_SEQUENTIAL
.It
SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
.It
SQLITE_IOCAP_POWERSAFE_OVERWRITE
.It
SQLITE_IOCAP_IMMUTABLE
.It
SQLITE_IOCAP_BATCH_ATOMIC
.El
.Pp
The SQLITE_IOCAP_ATOMIC property means that all writes of any size
are atomic.
The SQLITE_IOCAP_ATOMICnnn values mean that writes of blocks that are
nnn bytes in size and are aligned to an address which is an integer
multiple of nnn are atomic.
The SQLITE_IOCAP_SAFE_APPEND value means that when data is appended
to a file, the data is appended first then the size of the file is
extended, never the other way around.
The SQLITE_IOCAP_SEQUENTIAL property means that information is written
to disk in the same order as calls to xWrite().
.Pp
If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill in the
unread portions of the buffer with zeros.
A VFS that fails to zero-fill short reads might seem to work.
However, failure to zero-fill short reads will eventually lead to database
corruption.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 734.
.Bd -literal
typedef struct sqlite3_io_methods sqlite3_io_methods;
struct sqlite3_io_methods {
int iVersion;
int (*xClose)(sqlite3_file*);
int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
int (*xSync)(sqlite3_file*, int flags);
int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
int (*xLock)(sqlite3_file*, int);
int (*xUnlock)(sqlite3_file*, int);
int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
int (*xFileControl)(sqlite3_file*, int op, void *pArg);
int (*xSectorSize)(sqlite3_file*);
int (*xDeviceCharacteristics)(sqlite3_file*);
/* Methods above are valid for version 1 */
int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
void (*xShmBarrier)(sqlite3_file*);
int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
/* Methods above are valid for version 2 */
int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
/* Methods above are valid for version 3 */
/* Additional methods may be added in future releases */
};
.Ed
.Sh SEE ALSO
.Xr sqlite3_file 3 ,
.Xr sqlite3_file_control 3 ,
.Xr SQLITE_FCNTL_LOCKSTATE 3 ,
.Xr SQLITE_IOCAP_ATOMIC 3 ,
.Xr SQLITE_LOCK_NONE 3 ,
.Xr SQLITE_OK 3 ,
.Xr SQLITE_SYNC_NORMAL 3
|
