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 = 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.
All 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 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.
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