Crate vfsi_sync 

Synchronous filesystem contracts.

Application code uses Vfsi and VfsiExt. Backend implementers use backend::HandleBackend and backend::VectorBackend; shared defaults live in [backend::helpers].

Re-exports

pub use traits::ReadAllOptions;

Modules

api

Portable application contracts, operations, options, and extension workflows. Portable synchronous vectorized filesystem API.

backend

Native execution contracts for backend implementers and language bindings. Application callers use Vfsi and VfsiExt. Native synchronous backend contracts. HandleBackend supports owned handles; VectorBackend adds native vector engines and overridable workflows. Shared algorithms live in [crate::backend::helpers].

Structs

Adb

An Application Data Block (ADB) pattern, mirroring struct tc_adb.

AttrMask

A bitflags set of requested attributes.

Attrs

Idiomatic metadata returned by the Rust-native path API.

Capabilities

Typed backend capabilities. Unlike the legacy integer constants, this rejects accidental mixing with unrelated bit fields.

CopyOptions

Options for whole-file copies through crate::api::Vfsi::vcopy. Source final symlinks are followed by default; ancestor symlinks use normal namespace resolution. This is not a snapshot. When preserving a source symlink, its link text is copied and an existing destination is not replaced. Destination symlinks for data copies retain normal following behavior.

DepthLimit

A checked finite traversal depth or an explicitly unlimited traversal. The root has depth zero. Unlimited depth retains entry and byte budgets. Finite depths 0 through 65,533 are representable; larger values are rejected. Both this type and Option<DepthLimit> occupy two bytes.

DirEntry

One native directory entry with its already-fetched metadata.

DirectoryListing

One directory and its entries, with attributes fetched during enumeration.

ExtentPair

One extent to copy, mirroring struct tc_extent_pair.

FilesystemStats

Filesystem capacity and limits for the filesystem containing a target. Values are observations, not reservations. None means unknown or unsupported. Byte counts use the filesystem allocation unit, not its preferred I/O size. Getters preserve zero and false as known values. Fluent with_* setters accept None to restore an unknown value.

FsClient

Cloneable owner of one synchronous backend connection. Clones share a mutex and serialize backend calls; use separate connections for parallel RPCs. Explicitly close handles to observe cleanup failures. Handle Drop queues cleanup, drained before later operations or by drain_cleanup. Dropping the final backend owner performs synchronous teardown and may wait for pending closes and backend request timeouts.

FsDir

Owned, handle-rooted directory. Dropping it queues backend cleanup; close reports cleanup errors explicitly.

FsObjId

Filesystem-scoped identifier for an underlying filesystem object.

FsRead

Typed read request for FsClient::vread_native.

FsReadInto

Typed vector read into caller-provided storage.

FsReadIntoResult

Application result for one read into caller storage, in request order.

FsReadResult

Application result for one positional vector read, in request order.

FsWriteResult

Application result for one vector write, in request order. For completed append writes, offset + bytes_written is the last reported end; concurrent writers can interleave between short-write waves.

ListDirOptions

Shared directory traversal policy for collection and paged visiting. Defaults to immediate children only. Collection retains native batching; visiting delivers owned directory pages incrementally through callbacks. Unspecified budgets inherit the client’s resource limits. Require no symlink components when false; metadata’s final-component option has a deliberately different name.

MkDirOp

One directory creation with explicit Unix permission bits. Construction performs no I/O and can borrow the path without allocating. Parents must exist; submit independent siblings together with super::Vfsi::vmkdir.

OpenFile

Owned File Descriptor handle to one open instance, implementing crate::FileHandle.

OpenFlags

Typed file-open behavior for the Rust-native API.

OpenOp

One complete open request. This replaces three error-prone parallel slices of paths, flags, and modes.

OpenOptions

std::fs::OpenOptions-style builder for any Vfsi client.

Permissions

Rust-native permission bits, independent of protocol wire attributes.

ReadAllOptions

Resource limits for reading multiple complete files into memory.

ReadIntoResult

Metadata for a read placed directly into caller-provided storage.

ReadOp

One element of a batched read, replacing the C tc_iovec (which mixed input and output fields in a single mutable struct).

ReadOptions

Fluent configuration must be retained; discarding a changed copy is diagnosed.

ReadResult

The result of one ReadOp: the data and whether end-of-file was hit. file echoes the request’s file reference so results can be paired back to mixed fd/path inputs without reordering assumptions.

RemoveOptions

Options controlling recursive removal.

ResourceLimits

Default resource policy for a client. Per-call options override it. Byte limits bound logical payload, not allocator capacity or RPC overhead.

RpcError

An error from the low-level client: either an NFS4ERR_* status reported by the server for a compound operation, or a transport/RPC-level failure.

SetAttrsOp

One attribute update for a path or opened object.

StreamOptions

Tuning options for bounded single-file streaming reads.

VfAttrs

File attributes, mirroring struct tc_attrs. mode is the full st_mode (permission bits plus S_IFMT file-type bits); the mtime/atime/ctime fields hold seconds and nanoseconds.

VfError

The failure of one operation in a vectorized call.

WalkEntry

A directory and its entries, as returned by a filesystem walk. path is the directory’s root-relative path; entries are its immediate children.

WalkEvent

Root is depth zero. Symlinks are Entry events and are never followed.

WriteResult

The result of one crate::WriteOp. file echoes the request’s file reference.

Enums

ErrorDomain

Namespace in which a status code is meaningful.

FileOperand

Native backend operand: a File Descriptor, path, or special directory target.

SeekFrom

How filesystem seek operations interpret their offset, mirroring SEEK_SET / SEEK_CUR / SEEK_END as an enum.

StatusCode

Typed protocol/filesystem status. Transport failures have no status.

StreamCompletion

Completion of a streaming read. Stopping does not mean EOF.

Target

Borrowed filesystem operand: a path to resolve or an already-open object. Used by attribute updates, filesystem statistics, and scalar conveniences. Handle targets retain object identity across rename/unlink; path symlink policies do not change that identity. A target never owns or closes a handle.

TransportKind

Transport provenance, not a guarantee that an operation is safe to retry. Unknown failures remain Other; messages are never parsed to classify them.

TraversalCompletion

Completion of a callback-based directory traversal.

VfDir

An opaque handle to an open directory.

VfOffset

The offset of a read or write operation.

VfPathBase

The base a path is resolved against, replacing the C VF_FD_CWD / VF_FD_ABS sentinel descriptors.

VfType

The NFSv4 object type, replacing the raw NF4* wire codes in VfAttrs::ftype.

WalkControl

Callback decision. Pruning never reads the directory’s contents.

WalkEventKind

Enter/Leave surround a directory, including a pruned directory.

Constants

DEFAULT_DIRECTORY_MAX_ENTRIES

Default maximum number of entries returned by allocating directory APIs.

DEFAULT_DIRECTORY_MAX_PATH_BYTES

Default combined path-storage budget for allocating directory APIs.

DEFAULT_READV_MAX_TOTAL_BYTES

Default aggregate payload limit for owned vector reads.

DEFAULT_READ_ALLV_MAX_TOTAL_BYTES

Default aggregate payload limit for complete-file vector reads.

DEFAULT_READ_MAX_BYTES

Default payload limit for APIs that allocate and return complete contents.

DEFAULT_READ_STREAM_CHUNK_BYTES

Default size of each chunk delivered by the bounded single-file stream API.

DEFAULT_WALK_MAX_DEPTH

Default recursion depth for recursive walks.

ERR_ACCES

ERR_EBADF

ERR_EXIST

ERR_INVAL

ERR_IO

ERR_ISDIR

ERR_NOENT

Generic errno-style error codes (they coincide with the NFS4ERR codes for the same conditions, which the NFS backend reports).

ERR_NOTDIR

NF4BLK

NF4CHR

NF4DIR

NF4FIFO

NF4LNK

NF4REG

NFSv4 wire type codes (NF4*), used to decode/encode VfType.

NF4SOCK

STATUS_TRANSPORT

NFS4 status used for transport-level failures (there is no NFS status).

VF_CAP_HARDLINKS

The backend can create hard links and report their shared identity.

VF_CAP_LSTAT

The backend implements no-follow metadata operations (lstat semantics).

VF_CAP_NON_UTF8_PATHS

The backend accepts paths containing arbitrary non-UTF-8 Unix bytes.

VF_CAP_POSIX_METADATA

The backend reports and honors Unix mode/ownership/link-count metadata.

VF_CAP_SERVER_COPY

Capability bit returned by a backend’s capability query when it will currently attempt a server-side copy operation (NFSv4.2 COPY or SMB FSCTL_SRV_COPYCHUNK).

VF_CAP_SYMLINKS

The backend can create, inspect, and copy symbolic links without following them.

VF_CAP_UNIX_SEMANTICS

Capabilities shared by the complete Unix-like NFS and dummy backends.

VF_ERR_RPC

Errors that have no filesystem status (transport / client side).

VF_ERR_UNSUPPORTED

Requested feature is not implemented by this backend.

Traits

AsTarget

Borrow a target for metadata queries, attribute updates or filesystem statistics. Paths can be passed directly; use Target for handles or mixed vectors. Conversion performs no I/O. Clients convert each operand once at preflight and retain that target for routing, execution, and error context.

DirHandle

Owned directory retaining the opened object’s identity after rename or path replacement. Paths are diagnostic only; clients validate ownership and live state before handle-rooted operations. Failed try_close retains cleanup ownership.

FileHandle

Owned handle to one open file instance.

Vfsi

Vectorized filesystem operations for direct and routed application clients. Construction, builders and protocol-specific diagnostics stay concrete. Vectors are strict, ordered results on success, not transactions: errors can follow partially completed requests and never imply rollback. Generic vector and callback methods require static generic dispatch, not dyn Vfsi. It adds no boxing, data copies or serial-loop fallbacks.

VfsiExt

Scalar operations and convenience workflows alongside the Vfsi vectors.

Functions

error_from_rpc

Convert an RPC error using an explicitly chosen logical request index. None keeps the failure unattributed; it never invents index zero. Transport errors retain their transport category rather than becoming a filesystem status. The RPC’s wire-operation index is not used here.

error_from_rpc_indexed

Convert a semantic RPC failure using its wire-operation index. Transport failures have no trustworthy operation index and remain unattributed. Callers mapping compound operations to logical requests should instead use error_from_rpc with their mapped index.

file_type_from_nfs

file_type_to_nfs

The NFSv4 wire type code.

metadata_from_attrs

Backend attribute conversion; absent fields remain absent.

open_flags_to_libc

Translate the typed flags for compatibility backends.

Type Aliases

Fd

Backend-assigned numeric File Descriptor, represented as a C int.

FsWrite

Typed borrowed write request for FsClient::vwrite_native.

ReadStreamCallback

Callback used by vectorized streaming reads.

RpcResult

Convenience alias used throughout the low-level client.

VfRes

Result of a compound-style operation: () on success, or the index and error of the first failing operation.

VfResult

WriteOp

A native write with owned or borrowed target and payload storage. Positioning is always VfOffset, with packed create/truncate flags. The fixed policy types let constructors infer storage without annotations.