Documentation
¶
Overview ¶
Package beneath holds a name beneath a directory: every open, make, remove, rename and ownership change resolves its path from a directory the caller opened, and a path that would leave it is refused.
On Linux a Dir resolves each path with a single openat2(2) call carrying RESOLVE_BENEATH, so the kernel (or gVisor's equivalent) refuses a symlink that leads out of the directory at the moment of use, wherever in the path it sits. os.Root walks a path one directory at a time with openat(2) and O_NOFOLLOW, which gVisor does not apply to a symlinked directory, so an os.Root there opens through a link that was swapped in and out of its root. A Dir does not depend on that behaviour.
Where openat2 is missing (a kernel before 5.6, or a seccomp profile that predates it) and on every other operating system a Dir is an os.Root.
The package imports only the standard library: the runner image compiles it from its embedded sources with no module downloads.
Index ¶
- Variables
- type Dir
- func (d *Dir) Beneath() bool
- func (d *Dir) Chmod(rel string, mode fs.FileMode) error
- func (d *Dir) Close() error
- func (d *Dir) CreateRegular(rel string, perm fs.FileMode) (*os.File, error)
- func (d *Dir) FS() fs.FS
- func (d *Dir) Lchown(rel string, uid, gid int) error
- func (d *Dir) Mkdir(rel string, perm fs.FileMode) error
- func (d *Dir) MkdirAll(rel string, perm fs.FileMode) error
- func (d *Dir) Open(rel string) (*os.File, error)
- func (d *Dir) OpenFile(rel string, flag int, perm fs.FileMode) (*os.File, error)
- func (d *Dir) OpenNoLinks(rel string) (*os.File, error)
- func (d *Dir) OpenRegular(rel string) (*os.File, error)
- func (d *Dir) Remove(rel string) error
- func (d *Dir) Rename(oldRel, newRel string) error
- func (d *Dir) Stat(rel string) (fs.FileInfo, error)
Constants ¶
This section is empty.
Variables ¶
var ErrEscapes = errors.New("path escapes from parent")
ErrEscapes is the error of a path that leaves the directory it is resolved beneath: a ".." or an absolute path, or a symlink that leads out.
var ErrLink = errors.New("path passes through a symlink")
ErrLink is the error of OpenNoLinks for a path with a symlink in it.
var ErrNotRegular = errors.New("not a regular file")
ErrNotRegular is the error of CreateRegular for a name that is a link, a directory or a pipe.
Functions ¶
This section is empty.
Types ¶
type Dir ¶
type Dir struct {
// contains filtered or unexported fields
}
Dir is a directory that names are resolved beneath. It is safe for concurrent use; Close waits for the calls in progress.
func Open ¶
Open opens the directory name and returns a Dir on it. name itself is resolved as the operating system resolves any path; every name used through the Dir is held beneath it.
func (*Dir) Beneath ¶
Beneath says whether this Dir resolves paths with openat2 rather than an os.Root.
func (*Dir) CreateRegular ¶
CreateRegular opens rel for writing, creating it with perm when it is not there, and empties it. A link, a directory or a pipe in its place is refused with ErrNotRegular: nothing is written through a link or waited for.
func (*Dir) FS ¶
FS is the Dir as an fs.FS: a read-only view whose every open is held beneath the Dir.
func (*Dir) MkdirAll ¶
MkdirAll makes the directory rel and the ones missing on its way, each through the Dir, so none of them can be made beyond a link that leads out. A directory that is there, or a link to one beneath the Dir, is left as it is; a file in the way is an error.
func (*Dir) Open ¶
Open opens the file or directory rel for reading. A symlink in rel is followed only while it stays beneath the Dir.
func (*Dir) OpenNoLinks ¶
OpenNoLinks opens rel for reading, refusing a symlink anywhere in it, the last element included, with ErrLink. A file that is not a regular one is opened without blocking; it is for the caller to look at.
func (*Dir) OpenRegular ¶
OpenRegular opens rel for reading and returns the regular file it names. A link as the last element, a directory or a pipe in its place is refused with ErrNotRegular, and a pipe is not waited for. A link to a folder on the way is followed while it stays beneath the Dir. The file returned is the one that was looked at: it is described after it is opened.
func (*Dir) Remove ¶
Remove removes the file or the empty directory rel, a symlink itself and not what it points to.