Documentation
¶
Overview ¶
Package osfs provides a billy filesystem for the OS.
Index ¶
- Variables
- func New(baseDir string, opts ...Option) billy.Filesystem
- type BoundOS
- func (fs *BoundOS) Capabilities() billy.Capability
- func (fs *BoundOS) Chmod(path string, mode gofs.FileMode) error
- func (fs *BoundOS) Chroot(path string) (billy.Filesystem, error)
- func (fs *BoundOS) Create(name string) (billy.File, error)
- func (fs *BoundOS) Join(elem ...string) string
- func (fs *BoundOS) Lstat(name string) (os.FileInfo, error)
- func (fs *BoundOS) MkdirAll(name string, perm gofs.FileMode) error
- func (fs *BoundOS) Open(name string) (billy.File, error)
- func (fs *BoundOS) OpenFile(name string, flag int, perm gofs.FileMode) (billy.File, error)
- func (fs *BoundOS) ReadDir(name string) ([]gofs.DirEntry, error)
- func (fs *BoundOS) Readlink(name string) (string, error)
- func (fs *BoundOS) Remove(name string) error
- func (fs *BoundOS) RemoveAll(name string) error
- func (fs *BoundOS) Rename(from, to string) error
- func (fs *BoundOS) Root() string
- func (fs *BoundOS) Stat(name string) (os.FileInfo, error)
- func (fs *BoundOS) Symlink(oldname, newname string) error
- func (fs *BoundOS) TempFile(dir, prefix string) (billy.File, error)
- type Option
- type RootOS
- func (fs *RootOS) Capabilities() billy.Capability
- func (fs *RootOS) Chmod(path string, mode gofs.FileMode) error
- func (fs *RootOS) Chroot(path string) (billy.Filesystem, error)
- func (fs *RootOS) Create(name string) (billy.File, error)
- func (fs *RootOS) Join(elem ...string) string
- func (fs *RootOS) Lstat(name string) (os.FileInfo, error)
- func (fs *RootOS) MkdirAll(name string, perm gofs.FileMode) error
- func (fs *RootOS) Open(name string) (billy.File, error)
- func (fs *RootOS) OpenFile(name string, flag int, perm gofs.FileMode) (billy.File, error)
- func (fs *RootOS) ReadDir(name string) ([]gofs.DirEntry, error)
- func (fs *RootOS) Readlink(name string) (string, error)
- func (fs *RootOS) Remove(name string) error
- func (fs *RootOS) RemoveAll(name string) error
- func (fs *RootOS) Rename(from, to string) error
- func (fs *RootOS) Root() string
- func (fs *RootOS) Stat(name string) (os.FileInfo, error)
- func (fs *RootOS) Symlink(oldname, newname string) error
- func (fs *RootOS) TempFile(dir, prefix string) (billy.File, error)
- type Type
Constants ¶
This section is empty.
Variables ¶
var Default billy.Filesystem = newBoundOS(string(os.PathSeparator))
Default Filesystem representing the root of the os filesystem.
var ErrPathEscapesParent = errors.New("path escapes from parent")
ErrPathEscapesParent represents when an action leads to escaping from the dir the filesystem is bound to.
On non-js builds this aligns with os.Root's containment guarantees; the upstream error returned by os.Root is not exported, so this sentinel is exposed instead. On js/wasm the symbol is defined for API parity but is not returned by the in-memory implementation.
Functions ¶
func New ¶
func New(baseDir string, opts ...Option) billy.Filesystem
New returns a new OS filesystem rooted at baseDir.
The returned filesystem is always a BoundOS: containment is enforced via os.Root, opened and closed per operation. For better performance with caller-managed lifecycle, use FromRoot instead.
WithMmap enables an mmap-backed implementation of BoundOS.Open on supported platforms; all other Option values are accepted for API compatibility but have no effect on the returned implementation.
Types ¶
type BoundOS ¶
type BoundOS struct {
// contains filtered or unexported fields
}
BoundOS is a fs implementation based on the OS filesystem which relies on Go's os.Root. A new os.Root is opened and closed for each filesystem operation to avoid holding a directory handle open.
For better performance, prefer RootOS via FromRoot with a caller-managed os.Root.
Behaviours of note:
- Read and write operations can only be directed to files which descend from the base dir.
- Symlink targets are stored verbatim and not rewritten, so they may point outside the base dir or to non-existent paths. BoundOS.Readlink returns the stored target with path separators normalised to forward slashes (see filepath.ToSlash).
- Operations leading to escapes to outside the os.Root location result in ErrPathEscapesParent.
func (*BoundOS) Capabilities ¶
func (fs *BoundOS) Capabilities() billy.Capability
func (*BoundOS) Chroot ¶
func (fs *BoundOS) Chroot(path string) (billy.Filesystem, error)
Chroot returns a new BoundOS filesystem, with the base dir set to the result of joining the provided path with the underlying base dir.
type Option ¶
type Option func(*options)
func WithBoundOS ¶
func WithBoundOS() Option
WithBoundOS selects the BoundOS implementation.
BoundOS is the only OS-backed implementation returned by New, so this option is the default and is kept for API compatibility.
func WithMmap ¶
func WithMmap() Option
WithMmap opts the filesystem returned by New (and any RootOS returned by FromRoot) into an mmap-backed implementation of billy.File for read-only opens on platforms that support it (currently darwin and linux). On other platforms the option is accepted but has no effect.
EXPERIMENTAL: this option's semantics may change. Today every read-only BoundOS.Open / RootOS.Open (and any BoundOS.OpenFile / RootOS.OpenFile without write flags) returns a mmap-backed handle when the option is set. That includes small files and sequential-read workloads where mmap can be neutral or net- negative compared to plain file I/O. If we find a meaningful reason to make the opt-in finer-grained (per-call rather than per-FS), the option's effect on [Open]/[OpenFile] will narrow accordingly.
mmap also changes failure semantics: truncating the underlying file while a read is in flight raises SIGBUS instead of returning an error, and replacing the file via rename leaves the mapping pointing at the old inode. Callers that may see the file mutate underneath them should leave the option off.
The mmap-backed file is read-only by construction; it does not satisfy billy.Syncer (Sync is meaningless on a read-only mapping) or the [Locker] interface even though the surrounding filesystem advertises both capabilities. Code that type-asserts against those interfaces on a handle returned by an open with WithMmap active should be prepared for the assertion to fail.
type RootOS ¶
type RootOS struct {
// contains filtered or unexported fields
}
RootOS is a high-performance fs implementation based on a caller-managed os.Root. Since the root is reused across all operations, this avoids the overhead of opening and closing it on every call. The caller is responsible for the root's lifecycle.
For automatic lifecycle management at the cost of per-operation overhead, use BoundOS via New instead.
Behaviours of note:
- Read and write operations can only be directed to files which descend from the root dir.
- Symlink targets are stored verbatim and not rewritten, so they may point outside the root dir or to non-existent paths. RootOS.Readlink returns the stored target with path separators normalised to forward slashes (see filepath.ToSlash).
- Operations leading to escapes to outside the os.Root location result in ErrPathEscapesParent.
func FromRoot ¶
FromRoot creates a new RootOS from an os.Root. The provided root is used directly for all operations and the caller is responsible for its lifecycle. Root must not be nil.
WithMmap enables an mmap-backed billy.File from RootOS.Open (and RootOS.OpenFile when opened read-only) on supported platforms; all other Option values are accepted for API compatibility but have no effect.
func (*RootOS) Capabilities ¶
func (fs *RootOS) Capabilities() billy.Capability
func (*RootOS) Chroot ¶
func (fs *RootOS) Chroot(path string) (billy.Filesystem, error)
Chroot returns a logical sub-filesystem rooted at the result of joining the provided path with the underlying root dir. The returned filesystem reuses this RootOS's os.Root (no new file descriptor is opened), so its lifecycle is tied to the parent root managed by the caller.
If path does not yet exist under the parent root it is created (with [defaultDirectoryMode]). If path exists but is not a directory an error is returned.
Containment is enforced by the parent os.Root, not by the chroot path: operations cannot escape the parent root, but a symlink within the chroot may resolve to a sibling location elsewhere under the parent root. For a tighter boundary at the chroot path, open a new os.Root via os.OpenRoot and wrap it with FromRoot.
Source Files