fsutil

func MoveNoReplace ¶

func MoveNoReplace(src, dst string, observe ...MoveLifecycle) (step AtomicWriteStep, cat fserrors.Category, err error)

MoveNoReplace renames src to dst on the same filesystem and never overwrites an existing destination. It opens both parent directories without following a final symlink and performs the rename relative to those held descriptors using an atomic no-replace primitive, so the operation cannot be redirected by a symlink swap and a destination that materializes after a caller's preflight is never clobbered. It is same-filesystem only: a cross-device attempt fails with the kernel's EXDEV and the helper never falls back to copy+unlink. After the rename it revalidates that each held parent is still the directory reachable at its path (os.SameFile), rolling the rename back and failing closed if a parent moved mid-operation. The caller owns no descriptors; MoveNoReplace opens and closes everything it uses.

On failure it returns the step that failed and the error category. The underlying error is returned alongside so a consumer can branch without parsing strings: an existing destination wraps fs.ErrExist (RenameStep), a missing source wraps fs.ErrNotExist (RenameStep), a cross-device attempt wraps syscall.EXDEV (RenameStep), an unsupported platform wraps ErrNoReplaceUnsupported (RenameStep), and a parent that moved wraps ErrParentMoved (ParentSyncStep). The zero step and empty category mean success.

func WriteAtomic ¶

func WriteAtomic(targetPath string, data []byte, mode os.FileMode) (step AtomicWriteStep, cat fserrors.Category, err error)

WriteAtomic writes data to targetPath via a sibling temp file plus rename, fsyncing the temp file and parent directory. The parent directory must already exist. On failure it returns the step that failed and the error category.

func WriteAtomicCreateAt ¶

func WriteAtomicCreateAt(parentDir *os.File, targetName string, data []byte, mode os.FileMode, beforePublish ...PrePublish) (step AtomicWriteStep, cat fserrors.Category, published os.FileInfo, err error)

WriteAtomicCreateAt writes data to targetName only when nothing already exists there, using an already open parent directory. It never resolves the parent by path: temp creation, no-replace publish, cleanup, and parent sync all operate relative to parentDir. It is the create-only counterpart of WriteAtomic: where WriteAtomic publishes with os.Rename (which silently overwrites an existing target), this publishes with a hard link, which fails if targetName already exists — so a target that materialized between a caller's pre-authorization check and the publish is never clobbered. The published file carries exactly mode's permission bits regardless of the process umask. Every returned failure leaves no target and no temp residue. The caller owns parentDir and must close it after this call. targetName must be a single path component, not a relative path.

beforePublish is at most one optional pre-publish hook; passing none is the plain publish. It is variadic so the path-free create callers that predate the hook keep compiling unchanged.

published is the identity of the inode this call linked at targetName, and it is non-nil exactly when those bytes became visible under that name — including alongside a parent-sync failure, whose compensating removal happens after the entry was already reachable. A caller that has to reconcile or undo the create identifies it by that inode and never by the name, because another writer can replace the name between publication and the reconciliation.

func WriteAtomicReplaceAt ¶

func WriteAtomicReplaceAt(parentDir *os.File, targetName string, data []byte, mode os.FileMode, planned os.FileInfo, beforePublish PrePublish) (step AtomicWriteStep, cat fserrors.Category, published os.FileInfo, err error)

WriteAtomicReplaceAt writes data to targetName inside the already open parent directory, replacing whatever is there, and never resolves the parent by path: temp creation, the rename publish, cleanup, and the parent sync all run relative to parentDir. It is the descriptor-relative counterpart of WriteAtomic — a parent renamed or replaced after the caller opened it cannot redirect the write to a directory swapped in at the old path, because the held descriptor pins the inode. The published file carries exactly mode's permission bits regardless of the process umask. beforePublish is optional and, when non-nil, runs after the staged entry is durable and before anything becomes visible; its error aborts the publish leaving the target unchanged and no temp residue. The caller owns parentDir and must close it after this call. targetName must be a single path component, not a relative path.

planned is the identity of the file the caller computed data from, and is what closes the gap the descriptor cannot: the held descriptor pins the directory, not the entry inside it, so a plain rename replaces whatever answers to targetName at the instant the kernel resolves it — after any check the caller could have made. When planned is non-nil the publish refuses, wrapping ErrTargetIdentityChanged and leaving both files untouched, unless the entry it displaces is that exact file. Pass nil only when the caller has no expectation about what occupies the name.

published is the identity of the inode now answering to targetName, and it is non-nil exactly when publication happened — including alongside an error, because the parent fsync runs after the bytes are already visible and its failure does not take them back. A caller that may have to undo its own publish keeps it and passes it back as planned for that undo: the file it published is the only thing that undo may overwrite, and by then anything can occupy the name.

func SnapshotFileAt ¶

func SnapshotFileAt(parentDir *os.File, name string, maxBytes int64) (FileSnapshot, error)

SnapshotFileAt reads name under the already open directory parentDir and reports either that the entry is absent, or that it is a regular file together with its bytes, permission mode, and inode identity. Everything after the open — the type check, the size check, and the read — uses that one descriptor, so nothing is re-resolved by name between the check and the read and the bytes returned are the bytes of the inode that was checked.

name must be a single path component. A symlink is refused rather than followed (O_NOFOLLOW), and any non-regular entry is refused with ErrSnapshotNotRegular. The open is non-blocking so a FIFO or device entry is refused instead of hanging the caller. A file whose bytes exceed maxBytes is refused with ErrSnapshotTooLarge: the pre-read size check rejects an already oversized entry without reading it, and the read itself stops one byte past the cap so a file that grows between the two still fails rather than returning a snapshot larger than the caller allowed.