vfs

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package vfs is the operating system layer of SQLite, in Go: the files, locks and shared memory that os_unix.c gives a normal build. SQLite is built with SQLITE_OS_OTHER, and a small C shim turns its sqlite3_vfs and sqlite3_io_methods calls into calls of this package.

It behaves like os_unix.c, and keeps locks the same way: the Files of one database in the process share a node (see inode and shmNode) that counts in memory which File holds what, refuses conflicts between them without asking the kernel, and holds the process's locks on one descriptor. The kernel is asked only when the process's lock changes.

The difference is the kind of kernel lock. os_unix uses POSIX record locks, which belong to the process, and closing any descriptor of a file drops all of them, so os_unix keeps the descriptors of closed connections open until the last lock goes. This package uses locks on open file descriptions (OFD locks), which belong to the node's own descriptor: closing a File's descriptor drops nothing, so it is closed at once. The byte ranges are those of os_unix, so the locks also work against SQLite built from C, as long as that SQLite runs in another process.

One more difference: while no other process has the -shm open, the last reader of the process to leave one of the WAL read slots leaves the lock on the slot for about a millisecond, so that the next reader needs no system call. When another process opens the -shm, this process finds out within about that millisecond and from then on releases read slots at once, as os_unix, so that the other process's checkpoints are not held off (see shmReadSlots).

Results are SQLite result codes, with the values of sqlite3.h.

One File is used by one goroutine at a time. Different Files, also of the same path, may be used at the same time.

Index

Constants

View Source
const (
	OK       = 0
	Error    = 1
	Perm     = 3
	Busy     = 5
	NoMem    = 7
	ReadOnly = 8
	IOErr    = 10
	Full     = 13
	CantOpen = 14

	IOErrRead              = IOErr | 1<<8
	IOErrShortRead         = IOErr | 2<<8
	IOErrWrite             = IOErr | 3<<8
	IOErrFsync             = IOErr | 4<<8
	IOErrDirFsync          = IOErr | 5<<8
	IOErrTruncate          = IOErr | 6<<8
	IOErrFstat             = IOErr | 7<<8
	IOErrUnlock            = IOErr | 8<<8
	IOErrRdlock            = IOErr | 9<<8
	IOErrDelete            = IOErr | 10<<8
	IOErrNoMem             = IOErr | 12<<8
	IOErrAccess            = IOErr | 13<<8
	IOErrCheckReservedLock = IOErr | 14<<8
	IOErrLock              = IOErr | 15<<8
	IOErrClose             = IOErr | 16<<8
	IOErrShmOpen           = IOErr | 18<<8
	IOErrShmSize           = IOErr | 19<<8
	IOErrShmLock           = IOErr | 20<<8
	IOErrShmMap            = IOErr | 21<<8
	IOErrDeleteNoent       = IOErr | 23<<8
	IOErrGetTempPath       = IOErr | 25<<8
	IOErrCorruptFS         = IOErr | 33<<8

	CantOpenIsDir = CantOpen | 2<<8

	ReadOnlyCantInit  = ReadOnly | 5<<8
	ReadOnlyDirectory = ReadOnly | 6<<8

	// OKSymlink is what FullPathname returns when it followed a symbolic
	// link. SQLite turns it into OK, or into SQLITE_CANTOPEN_SYMLINK when the
	// database was opened with SQLITE_OPEN_NOFOLLOW.
	OKSymlink = OK | 2<<8
)

Result codes, with the values of sqlite3.h.

View Source
const (
	OpenReadOnly      = 0x00000001
	OpenReadWrite     = 0x00000002
	OpenCreate        = 0x00000004
	OpenDeleteOnClose = 0x00000008
	OpenExclusive     = 0x00000010
	OpenAutoProxy     = 0x00000020
	OpenURI           = 0x00000040
	OpenMemory        = 0x00000080
	OpenMainDB        = 0x00000100
	OpenTempDB        = 0x00000200
	OpenTransientDB   = 0x00000400
	OpenMainJournal   = 0x00000800
	OpenTempJournal   = 0x00001000
	OpenSubjournal    = 0x00002000
	OpenSuperJournal  = 0x00004000
	OpenWAL           = 0x00080000
	OpenNoFollow      = 0x01000000
)

Open flags (SQLITE_OPEN_*).

View Source
const (
	LockNone      = 0
	LockShared    = 1
	LockReserved  = 2
	LockPending   = 3
	LockExclusive = 4
)

Lock levels (SQLITE_LOCK_*).

View Source
const (
	ShmUnlock    = 1
	ShmLock      = 2
	ShmShared    = 4
	ShmExclusive = 8
	ShmNLock     = 8
)

Shared memory lock flags (SQLITE_SHM_*).

View Source
const (
	SyncNormal   = 0x00002
	SyncFull     = 0x00003
	SyncDataOnly = 0x00010
)

Sync flags (SQLITE_SYNC_*).

View Source
const (
	AccessExists    = 0
	AccessReadWrite = 1
	AccessRead      = 2
)

Access flags (SQLITE_ACCESS_*).

View Source
const (
	IOCapPowersafeOverwrite = 0x00001000
	IOCapSubpageRead        = 0x00008000
)

Device characteristics (SQLITE_IOCAP_*).

View Source
const (
	// MaxPathname is the size of the buffer FullPathname fills, as
	// os_unix's MAX_PATHNAME. Give it to SQLite as sqlite3_vfs.mxPathname.
	MaxPathname = 512
)

Variables

This section is empty.

Functions

func Access

func Access(name string, flags int) (bool, int)

Access tells whether name exists (as os_unix, an empty regular file does not), or can be read and written, or read.

func Delete

func Delete(name string, syncDir bool) int

Delete deletes name, and syncs its directory when syncDir is set.

func FullPathname

func FullPathname(name string) (string, int)

FullPathname is os_unix's unixFullPathname: the absolute path of name, with ".", ".." and symbolic links resolved one part at a time. The result code is OKSymlink when a link was followed: give it to SQLite as it is. A path that does not fit in MaxPathname bytes is SQLITE_CANTOPEN.

func ShmBarrier

func ShmBarrier()

ShmBarrier is a full memory barrier, as sqlite3MemoryBarrier (__sync_synchronize): MFENCE on amd64, DMB ISH on arm64. No load or store moves across it in either direction. A Go atomic is not enough on arm64: without LSE it is a LDAXR/STLXR loop, which lets an earlier store pass a later load.

Types

type File

type File struct {
	// contains filtered or unexported fields
}

File is an open file, as os_unix's unixFile.

func Open

func Open(name string, flags int) (f *File, outFlags int, rc int)

Open opens name with SQLITE_OPEN_* flags, as os_unix's unixOpen. An empty name is a temporary file, deleted when closed. outFlags are the flags the file was opened with: READONLY in place of READWRITE and CREATE when it could only be opened for reading.

func (*File) CheckReservedLock

func (f *File) CheckReservedLock() (bool, int)

CheckReservedLock tells whether some File, of this process or another, holds RESERVED or more.

func (*File) Close

func (f *File) Close() int

Close closes the file, and its shared memory if ShmUnmap was not called. The locks the File holds are released, and those of other Files of the database are kept. Closing twice is harmless.

func (*File) DeviceCharacteristics

func (f *File) DeviceCharacteristics() int

DeviceCharacteristics is that of os_unix with powersafe overwrite on, the default of SQLite.

func (*File) HasMoved

func (f *File) HasMoved() bool

HasMoved is SQLITE_FCNTL_HAS_MOVED: the path the main database was opened with no longer names this file (renamed, deleted or replaced).

func (*File) Lock

func (f *File) Lock(level int) int

Lock raises the lock to level: SHARED, RESERVED or EXCLUSIVE. SQLite never asks for PENDING. When EXCLUSIVE fails from RESERVED, the File keeps PENDING, so that the next try does not race new readers.

func (*File) LockState

func (f *File) LockState() int

LockState is the lock level held, for SQLITE_FCNTL_LOCKSTATE.

func (*File) ReadAt

func (f *File) ReadAt(p []byte, off int64) int

ReadAt reads len(p) bytes at off. When the file ends first, the rest of p is zeroed and the result is SQLITE_IOERR_SHORT_READ.

func (*File) SectorSize

func (f *File) SectorSize() int

SectorSize is os_unix's SQLITE_DEFAULT_SECTOR_SIZE.

func (*File) SetChunkSize

func (f *File) SetChunkSize(n int)

SetChunkSize is SQLITE_FCNTL_CHUNK_SIZE: Truncate and SizeHint round the size up to whole chunks of n bytes. 0 turns it off.

func (*File) ShmLock

func (f *File) ShmLock(offset, n, flags int) int

ShmLock locks or unlocks n slots of the wal-index from offset, as os_unix's unixShmLock. flags is SQLITE_SHM_LOCK or SQLITE_SHM_UNLOCK with SQLITE_SHM_SHARED or SQLITE_SHM_EXCLUSIVE. A shared lock is on one slot. SQLite never asks for a lock it holds, nor moves a slot between shared and exclusive without unlocking it first.

func (*File) ShmMap

func (f *File) ShmMap(n, size int, extend bool) (uintptr, int)

ShmMap returns the address of region n of the wal-index, each region size bytes. When the region is not there yet, extend makes it, and without extend the address is 0 and the result OK. The memory stays mapped until ShmUnmap. With a -shm that can only be read, the result is SQLITE_READONLY with the address, or SQLITE_READONLY_CANTINIT when no other connection has it open.

func (*File) ShmUnmap

func (f *File) ShmUnmap(remove bool) int

ShmUnmap detaches the File from the wal-index and releases the slots it still holds. The last File of the process unmaps the memory and closes the -shm, which drops the DMS lock. remove then deletes the file: SQLite asks for that only while it holds EXCLUSIVE on the database and no other connection has the -shm open. Without a wal-index it does nothing.

func (*File) Size

func (f *File) Size() (int64, int)

Size is the size of the file. As os_unix, a size of 1 is given as 0: a work around for the msdos file system of OS X, kept so that SQLite sees the same sizes it would see with os_unix.

func (*File) SizeHint

func (f *File) SizeHint(size int64) int

SizeHint is SQLITE_FCNTL_SIZE_HINT, as os_unix's fcntlSizeHint: with a chunk size set, make the file at least size bytes, rounded up to whole chunks. Without a chunk size it does nothing, as os_unix when memory mapped I/O is off.

func (*File) Sync

func (f *File) Sync(flags int) int

Sync writes the file to disk, and the directory entry of a new journal the first time. See fullFsync for what each system does.

func (*File) Truncate

func (f *File) Truncate(size int64) int

Truncate sets the size of the file, rounded up to whole chunks when SetChunkSize was called.

func (*File) Unlock

func (f *File) Unlock(level int) int

Unlock lowers the lock to level: SHARED or NONE. The process keeps its read lock while another of its Files holds SHARED.

func (*File) WriteAt

func (f *File) WriteAt(p []byte, off int64) int

WriteAt writes p at off. A full disk is SQLITE_FULL.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL