Documentation
¶
Overview ¶
Package fsutil provides filesystem utility functions.
Index ¶
- Variables
- func AtomicWriteFile(ctx context.Context, path string, data []byte) error
- func AtomicWriteFileMode(ctx context.Context, path string, data []byte, mode os.FileMode) error
- func CommitAtomicWrite(tmpPath, finalPath string) error
- func PrepareAtomicWrite(ctx context.Context, path string, data []byte) (tmpPath string, cleanup func(), err error)
- func ReadBounded(ctx context.Context, path string, maxBytes int64) ([]byte, error)
- type WriteError
- type WritePhase
Constants ¶
This section is empty.
Variables ¶
var ErrEmptyPath = errors.New("atomic write: empty path")
ErrEmptyPath is returned when an atomic write is called with an empty path.
var ErrFileTooLarge = errors.New("file too large")
ErrFileTooLarge is a sentinel error for file-size-exceeded conditions in fsutil. Wrap it with fmt.Errorf("%w: ...") so callers can use errors.Is.
var ErrUnsafePath = errors.New("atomic write: unsafe path")
ErrUnsafePath is returned when a path argument fails the local safety check (non-absolute, contains "..", or otherwise invalid). Callers are expected to pass paths derived from validated identifiers joined to a base directory; this guard makes the property local to fsutil so CodeQL's go/path-injection analyzer can prove safety without tracking validation across package boundaries.
Functions ¶
func AtomicWriteFile ¶
AtomicWriteFile writes data to a temp file and renames it to path, preventing corruption on crash. The context allows early bailout between expensive I/O steps when the caller has been cancelled.
func AtomicWriteFileMode ¶
AtomicWriteFileMode writes data to path atomically with the specified permissions. Checks ctx.Err() between expensive I/O steps to allow cancellation.
func CommitAtomicWrite ¶
CommitAtomicWrite renames the prepared temp file to the final path and fsyncs the parent directory.
func PrepareAtomicWrite ¶
func PrepareAtomicWrite(ctx context.Context, path string, data []byte) (tmpPath string, cleanup func(), err error)
PrepareAtomicWrite creates a temp file with data written, synced, and closed — ready for a final rename. Checks ctx.Err() between I/O steps.
func ReadBounded ¶
ReadBounded opens a file, checks its size against maxBytes, and reads it with a LimitReader. Returns an error if the file exceeds the size limit. Checks ctx.Err() after Open and after Stat to allow cancellation before the potentially large ReadAll.
Types ¶
type WriteError ¶
type WriteError struct {
Err error
Phase WritePhase
}
WriteError wraps an atomic-write failure with the phase that failed. Callers can use errors.As to inspect the phase without string matching.
func (*WriteError) Error ¶
func (e *WriteError) Error() string
func (*WriteError) Unwrap ¶
func (e *WriteError) Unwrap() error
type WritePhase ¶
type WritePhase int
WritePhase identifies which step of an atomic write failed.
const ( PhaseTempCreate WritePhase = iota + 1 PhaseTempWrite PhaseTempChmod PhaseTempSync PhaseTempClose PhaseRename )
WritePhase constants identify which step of an atomic write failed.
func (WritePhase) String ¶
func (p WritePhase) String() string