Eio_fs_unixSourcePOSIX filesystem calls that Eio and Unix do not bind.
Eio_fs_unix is for a program that links unix anyway, beside the portable machinery of Eio_fs.Sync. It holds the barriers that go through the drive's cache (on Darwin fcntl F_FULLFSYNC, where fsync stops in it), a filesystem's capacity, copy-on-write clones, tree removal in batches, positioned reads and writes, the sparse map, exclusive rename, POSIX record locks, lock files and their leases, extended attributes, regular files read without waiting on a FIFO, batches confined beneath a directory, and a root whose calls run on the calling thread.
A call that takes an Eio.Path.t or an Eio.File.t reports a failure as Eio.Io, as Eio's own backends do; one that takes a Unix.file_descr raises Unix.Unix_error, as Unix does.
sync_dir dir makes dir's entries durable: the barrier a commit protocol issues after renaming a file into place. A backend that registers a Eio_fs.Sync.Dir_sync answers through it, asked for a full barrier, so Eio_fs_chaos.Power under ~os:`Macos keeps what it commits. A plain POSIX directory is opened, every component resolved beneath dir's capability, and the descriptor that open returns is synced off the calling fiber's thread: by fcntl F_FULLFSYNC on Darwin, falling back to fsync on a filesystem that refuses it (SMB, exFAT), and by fsync elsewhere. A directory whose handle carries no descriptor takes Eio.Path.sync_dir, and raises as it does.
sync_file file makes file's data durable: the barrier a commit protocol issues over the bytes it wrote. A backend that registers a Eio_fs.Sync.File_sync answers through it, asked for a full barrier and before any descriptor file carries, so a model of power loss observes the barrier. A POSIX file, one open for reading only included, is synced on its descriptor as sync_dir syncs a directory's; a bare host descriptor is synced as the file Eio_unix.File.import_ro makes of it. A file with neither a registration nor a descriptor is synced by its own Eio.File.sync.
barrier is sync_file and sync_dir as the barriers a publication of Eio_fs.Sync issues: pass it as ~barrier for a publication that is durable on Darwin through the drive's cache.
type statvfs = {block_size : int64;The fragment size in bytes (f_frsize).
total_blocks : int64;The filesystem's size in blocks (f_blocks).
free_blocks : int64;The free blocks (f_bfree).
available_blocks : int64;The free blocks an unprivileged process can use (f_bavail).
}The type for filesystem capacities, as POSIX statvfs reports them. free_blocks and available_blocks differ by the reserve kept for the privileged user, so a caller needs both to say whether a filesystem is full from an unprivileged writer's position.
statvfs path reports the fragment size, total blocks, free blocks and blocks available to an unprivileged process on the filesystem holding path. The call is made on a system thread.
path is reached through its directory, never by its native name: the directory holding path is opened as Eio.Path.open_dir opens it, so a confined directory refuses a .. above it, an absolute path and a symbolic link leading out, and path's last component is opened beneath it without being followed (fstatvfs on it). A final symbolic link reports the filesystem holding the link. The empty path names the directory itself.
volume_used path is the bytes the volume holding path uses itself. On Darwin it is the volume's ATTR_VOL_SPACEUSED (getattrlist), what diskutil gives as its Volume Used Space: an APFS volume shares its container's space with the container's other volumes, and statvfs gives the container's size and free blocks, so their difference is what all of them hold. Elsewhere a filesystem is a volume of its own, and this is statfs's blocks less its free blocks. path is reached as statvfs reaches it, and the call is made on a system thread.
clone_tree src dst clones the file src, or the directory src with everything under it, to dst, which must not exist, in one copy-on-write operation that shares the data blocks: clonefile(2) on Darwin. The clone keeps modes, times, symbolic links and extended attributes, and is owned by the caller. It is true iff it cloned, and false, with nothing written, when the file system has no such operation or src and dst are on two volumes. Linux clones one file at a time (FICLONE) and has no call for a tree, so there it is always false: a tree cloned file by file costs a call per entry, which a caller that wants it walks itself. The call is made on a system thread; a clone of a directory is one call whatever it holds. As for statvfs, src and dst are each reached through their directory and never lead outside it (clonefileat); a final symbolic link src is cloned as a link (CLONE_NOFOLLOW).
type removed = {entries : int;The files, links and directories removed.
*)bytes : int;What the non-directories removed weighed.
*)refused : string list;Each path the removal refused, with the system's reason, in the order they were met; [] when nothing is left at the path.
}The type for what rmtree did.
rmtree path is like Eio.Path.rmtree but says what it removed and what it refused, and goes on past a refusal. It removes path and, when it is a directory, everything under it, deepest first, each entry reached through path's own directory capability (Batch): a symbolic link is removed and never followed. It costs a stat and an unlink per entry and a listing per directory, in hops per directory: a directory's entries are stated in one and unlinked in the next, whatever they number, and the hops of different directories run at once, four at a time. A cancellation ends it at the next hop, so none outlasts one directory's entries.
With ~grant:true (defaults to false) each directory is granted its owner's read, write and search before it is read, as Eio_fs.Tree.grant_owner grants it. The entry last of path, if any, is removed only once every other entry is gone, so a removal that fails leaves it. An entry another process removes meanwhile counts nothing, and a path that does not exist removes nothing. A refusal stops no other directory's removal, leaves the directories above it and last, and a later call goes on with what is left.
A program that reads and writes a file at offsets it names, as a database reads its pages, makes one call per page. Eio.File.pread reads into a Cstruct.t and may hand the call to a system thread; pread and pwrite read into bytes and write from a string on the calling thread, in one system call. A program that holds a host descriptor opens it as a file with Eio_unix.File.import_rw.
val pread :
?cached:bool ->
_ Eio.File.ro ->
file_offset:int ->
bytes ->
pos:int ->
len:int ->
intpread ~cached file ~file_offset buf ~pos ~len is like Eio.File.pread but reads into bytes, in one system call on the calling thread, where Eio's takes a Cstruct.t list and may hand the call to a system thread. It reads up to len bytes of file from byte file_offset into buf at pos, and is the count read, 0 at the end of the file. It reads at most 65,536 bytes, and file's own offset does not move:
Positioned answers it;pread, which Unix does not bind, retried on EINTR;Eio.File.pread.On a host descriptor, other threads run during the call. With cached (defaults to false) the read is one the page cache answers, such as a database page read again: it keeps the OCaml runtime lock and lands in buf with no copy, which costs less than giving the lock up and taking it back. On Linux it asks with RWF_NOWAIT and gives the lock up only for a read that would wait on the device; elsewhere it keeps the lock whatever the read waits on, so no other thread of the domain runs, and no other domain completes a minor collection, until it returns.
pwrite file ~file_offset s ~pos ~len is like Eio.File.pwrite_single but writes from a string, in one system call on the calling thread. It writes up to len bytes of s from pos to file at byte file_offset, and is the count written. It writes at most 65,536 bytes, file's own offset does not move, and file answers it as it answers pread: through Positioned, by POSIX pwrite on a host descriptor, retried on EINTR while other threads run, or by one Eio.File.pwrite_single.
The positioned calls of a file that answers them itself.
type Eio.Resource.pi += | Positioned : ('t, (module POSITIONED with type t = 't), [> `Positioned ])
Eio.Resource.piThe positioned calls a file registers in its resource handler when it answers them itself: a wrapper that carries the descriptor it stands in front of, to count, observe or alter its calls, registers it, and pread and pwrite then go through the wrapper. The wrapper reaches its base with pread and pwrite too.
seek_data fd ~file_offset is the next offset at or after file_offset that starts allocated data, and None when there is none: a hole runs to the end of the file, or file_offset is at or past it. This is lseek(SEEK_DATA), which Unix.lseek has no whence for. The offset is absolute and the call moves fd's position as lseek does. The call is made on a system thread.
seek_hole fd ~file_offset is like seek_data for the next offset at or after file_offset that starts a hole. The end of the file counts as one, so this is None only when file_offset is at or past the end. This is lseek(SEEK_HOLE).
type extent = {logical : int;The extent's offset in the file.
*)physical : int;The extent's offset on the device.
*)length : int;The extent's length in bytes.
*)}extents fd ~file_offset ~length ~max is the physical extents backing the length bytes of fd's file from byte file_offset, in increasing logical order, at most max of them. This is F_LOG2PHYS_EXT on Darwin and FS_IOC_FIEMAP on Linux, neither of which Unix binds.
The answer stops at the first hole, the end of the range, max, or bytes the filesystem accepted but has not placed, or placed with no block address of their own (inline, unaligned, encoded or encrypted data). An empty range has no extent. A walk steps past the last extent returned and asks again, ending when the answer is empty. max is the batch, so one system-thread hop covers many extents.
exclusive_rename is the POSIX backend for atomic no-replace publication. Directory wrappers are consulted before resolving the source and target parents through their capabilities. Linux uses renameat2(RENAME_NOREPLACE), FreeBSD renameat2(AT_RENAME_NOREPLACE) and Darwin renameatx_np(RENAME_EXCL); unsupported platforms or filesystems refuse. An existing target, including a symbolic link, is never overwritten.
Through Eio_fs.Sync.Rename.exclusive, it raises Eio.Io with Eio.Fs.error.Already_exists for an existing target, Eio.Io as the platform call fails otherwise (an unsupported platform or filesystem included), and Invalid_argument for a path that ends in no file name or whose directory carries no Unix descriptor.
val lock_range :
Unix.file_descr ->
[ `Read | `Write | `Unlock ] ->
file_offset:int ->
length:int ->
boollock_range fd kind ~file_offset ~length sets a POSIX record lock of kind on the length bytes of fd's file from byte file_offset, without waiting (fcntl F_SETLK), placed from the start of the file; a length of 0 runs to the end of the file, however far it grows. It is true iff the lock is set, and false if another process holds a lock that conflicts; `Unlock is always true. fd's file offset does not move, where Unix.lockf places its range at the offset and so has to be preceded by a seek. A lock this process holds there already is replaced.
val range_holder :
Unix.file_descr ->
file_offset:int ->
length:int ->
[ `Free | `Held of int option ]range_holder fd ~file_offset ~length is the record lock another process holds that would refuse a write lock on the length bytes of fd's file from byte file_offset (fcntl F_GETLK), in the shape probe answers: `Held (Some pid) where process pid holds it, `Held None where the kernel names no process, and `Free where none is held. This process's own locks never count.
val await_record_lock : Unix.file_descr -> unitawait_record_lock fd takes the exclusive POSIX record lock, a write lock, over fd, from its offset to the end of the file as lockf does, by the kernel's blocking request (fcntl F_SETLKW), and returns once the kernel grants it. The request waits on a thread of its own and the calling fiber waits for its answer, so the domain goes on running other fibers; a cancel withdraws the request, and a lock granted in that instant is let go.
It is the wait under with_lock, for a caller that keeps its own descriptors: the record lock belongs to the process, and closing any descriptor on the file drops it.
type block = [ | `YesWait for the holder.
*)| `No| `FibersWait for a fiber of this process; refuse another process's hold.
*)| `For of floatWait up to that many seconds of the monotonic clock, then refuse.
*) ]The type for what a take does when another caller holds the lock.
type create = [ | `Never| `If_missing of Eio.File.Unix_perm.tCreate an absent file with that mode, less the umask.
*) ]The type for what a take does when the lock file is absent.
type refusal = {path : string;The native path of the lock file.
*)holder : int option;The process holding the lock when it was refused: this process when a fiber of it holds it, otherwise the process the kernel reports holding the record lock (fcntl F_GETLK). None when the holder let go before it could be asked, and for a Lease, whose flock the kernel names no holder of.
contents : string;The lock file's first 4096 bytes when the lock was refused: what the holder wrote through contents, or "". It is read without the lock, so it is a diagnostic; holder is the answer.
}The type for a refused lock: which file, and who holds it.
Raised by a take, such as with_lock, that another holder refuses as its block policy says. It prints as pp_refusal does.
pp_refusal formats a refusal as "<path> is held by process <pid>" for another process, "<path> is held by another fiber of this process: <line>" for a fiber of this one, <line> the first line of its contents, or "<path> is held" when its holder is None.
val with_lock :
?block:block ->
?create:create ->
?contents:string ->
?on_wait:(unit -> unit) ->
_ Eio.Path.t ->
(unit -> 'a) ->
'awith_lock path fn opens (or creates) path, takes an exclusive advisory lock, and runs fn () while holding it. Waiting for the operating-system lock suspends only the calling fiber. The lock is released when fn returns or raises.
create (defaults to `If_missing 0o600, owner-only) says what an absent lock file does. contents, when present, replaces the lock file's contents through the locked handle. block (defaults to `Yes) says what a hold another caller already has does. Locks are coordinated between fibers by device and inode, and between processes by the POSIX record lock. It also excludes Lease readers and writers. On Linux, where BSD flock and POSIX record locks are independent, it takes an exclusive flock too; on Darwin the record lock already conflicts with leases.
With `Yes or `For seconds, a POSIX record lock another process holds is waited for by the kernel's blocking request (fcntl F_SETLKW), which answers when that process lets go: the lock is asked for once without waiting, on_wait () is called once if it is held (it does nothing by default), and the request follows. A cancelled wait withdraws the request and answers at the cancel, and `For seconds withdraws it at its bound. With `Yes, `Fibers or `For seconds, a lock a fiber of this process holds is waited for in this process, and on_wait () is called before that wait too. A wait for a BSD lease on Linux polls as Lease.with_exclusive's does.
path must be the lock's own regular file: a link, a directory, a FIFO, or a name that took the entry between resolution and open is refused with Eio.Fs.error.Permission_denied carrying Not_a_lock_file. A backend with no Unix descriptor is refused unless it registers Eio_fs.Sync.Process_local.
val probe : _ Eio.Path.t -> [ `Free of string | `Held of refusal ]probe path is the lock over path as an acquisition would find it now, taken without acquiring it: `Held r names its holder as a refusal does, and `Free contents carries the lock file's first 4096 bytes, what its last holder left there. The file is opened for reading only, and a descriptor on a lock this process holds is never closed while it is held, so a probe from the holding process keeps the hold.
path must be the lock's own regular file, as with_lock's must. A name given to another regular file while the probe reads it is probed again, for the file it holds then.
module Held : sig ... endA lock held for as long as its holder says, restated as it goes.
module Lease : sig ... endLeases: BSD flock locks, which belong to an open file description rather than to the process that took them.
val lock_section :
?block:block ->
?create:create ->
?contents:string ->
_ Eio.Path.t ->
Eio_fs.Sync.Lock.tThe name-value pairs a filesystem keeps beside a file's data (xattr(7)), which Unix does not bind. As for statvfs, path is reached through its directory and never leads outside it. Both calls act on the entry path names, a symbolic link included, and never follow it: Darwin opens the entry (O_SYMLINK) and calls flistxattr, fgetxattr and fsetxattr on it, so the entry must be readable; Linux calls llistxattr, lgetxattr and lsetxattr on the entry through its directory's /proc/self/fd link, and fails with ENOTSUP where /proc is not mounted. Each call is made on a system thread.
xattrs path is every extended attribute of path as (name, value) pairs, in ascending byte order of name, and [] for an entry that has none. A value is the attribute's bytes, NUL bytes included. An attribute removed between the listing and the read is left out.
set_xattr path name value sets the extended attribute name of path to value, creating it or replacing it.
The type for a regular file read: its bytes and its permission bits, both from the one descriptor.
val read_regular :
max_bytes:int ->
_ Eio.Path.t ->
(regular option, Eio_fs.Nofollow.error) resultread_regular ~max_bytes path is like Eio_fs.Nofollow.read_file but opens path's last component with O_NONBLOCK | O_NOCTTY too, so a FIFO is refused without waiting for a writer and a terminal never becomes the controlling one, reads an absent entry as None, and gives the file's permission bits. It is Ok (Some r), r the bytes read from the descriptor openat gives with O_NOFOLLOW and its permission bits by fstat, or Ok None if the entry is absent. It is Error `Too_large for a file of more than max_bytes bytes or one that grows beyond its size at open, and Error (`Invalid msg) for a symbolic link or another non-regular entry and for a failed open, msg naming the path. The descriptor is closed before the result. path's parent is opened as Eio.Path.open_dir opens it; Eio_fs.Nofollow.with_parent hands over a path whose parents follow no symbolic link.
Warning. A hard link is the file it names, wherever its other names are: a regular file linked beneath the parent from outside the root is read. Only a process that can write both directories makes such a link.
inline_fs fs is the unconfined root fs, such as Eio.Stdenv.fs env, whose stat, open_in, open_out, read_link, read_dir and with_dir_entries make their system calls on the calling thread, where eio_posix hands each to a system thread and back, which costs more CPU than the call. A link read of a name ending in a slash is the root's. A file it opens is the root's own kind of file, and every other operation, a directory opened from it included, is the root's. An error is the root's in what it says: the operation, the path, the kind of error and its errno; the system call it names is the one made here, which may not be the backend's. The calls block the calling domain while they run, which on a local disk is microseconds; a filesystem whose calls can block for longer, such as a network mount, is better reached through fs itself.