beneath

package
v0.7.51-dev.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 9 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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.

View Source
var ErrLink = errors.New("path passes through a symlink")

ErrLink is the error of OpenNoLinks for a path with a symlink in it.

View Source
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

func Open(name string) (*Dir, error)

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

func (d *Dir) Beneath() bool

Beneath says whether this Dir resolves paths with openat2 rather than an os.Root.

func (*Dir) Chmod

func (d *Dir) Chmod(rel string, mode fs.FileMode) error

Chmod changes the mode of rel, which must be readable.

func (*Dir) Close

func (d *Dir) Close() error

Close closes the directory.

func (*Dir) CreateRegular

func (d *Dir) CreateRegular(rel string, perm fs.FileMode) (*os.File, error)

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

func (d *Dir) FS() fs.FS

FS is the Dir as an fs.FS: a read-only view whose every open is held beneath the Dir.

func (*Dir) Lchown

func (d *Dir) Lchown(rel string, uid, gid int) error

Lchown changes the owner of rel, a symlink itself and not what it points to.

func (*Dir) Mkdir

func (d *Dir) Mkdir(rel string, perm fs.FileMode) error

Mkdir makes the directory rel, whose parent must be beneath the Dir.

func (*Dir) MkdirAll

func (d *Dir) MkdirAll(rel string, perm fs.FileMode) error

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

func (d *Dir) Open(rel string) (*os.File, error)

Open opens the file or directory rel for reading. A symlink in rel is followed only while it stays beneath the Dir.

func (*Dir) OpenFile

func (d *Dir) OpenFile(rel string, flag int, perm fs.FileMode) (*os.File, error)

OpenFile is os.OpenFile of rel beneath the Dir.

func (d *Dir) OpenNoLinks(rel string) (*os.File, error)

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

func (d *Dir) OpenRegular(rel string) (*os.File, error)

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

func (d *Dir) Remove(rel string) error

Remove removes the file or the empty directory rel, a symlink itself and not what it points to.

func (*Dir) Rename

func (d *Dir) Rename(oldRel, newRel string) error

Rename renames oldRel to newRel, both beneath the Dir.

func (*Dir) Stat

func (d *Dir) Stat(rel string) (fs.FileInfo, error)

Stat describes rel, following a symlink only while it stays beneath the Dir. It opens the name without blocking, so a pipe is described, not waited for.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL