package platform

import "github.com/tetratelabs/wazero/internal/platform"

Package platform includes runtime-specific code needed for the compiler or otherwise.

Note: This is a dependency-free alternative to depending on parts of Go's x/sys. See /RATIONALE.md for more context.

Index ¶

• Constants
• Variables
• func Chown(path string, uid, gid int) error
• func ChownFile(f fs.File, uid, gid int) error
• func CompilerSupported() bool
• func FakeNanosleep(int64)
• func FakeOsyield()
• func Fdatasync(f fs.File) (err error)
• func IsTerminal(fd uintptr) bool
• func Lchown(path string, uid, gid int) error
• func Lstat(path string, st *Stat_t) error
• func MmapCodeSegment(code io.Reader, size int) ([]byte, error)
• func MunmapCodeSegment(code []byte) error
• func Nanosleep(ns int64)
• func Nanotime() int64
• func NewFakeNanotime() *sys.Nanotime
• func NewFakeRandSource() io.Reader
• func NewFakeWalltime() *sys.Walltime
• func OpenFile(name string, flag int, perm fs.FileMode) (f *os.File, err error)
• func Readdirnames(f fs.File, n int) (names []string, err error)
• func Rename(from, to string) error
• func Stat(path string, st *Stat_t) error
• func StatFile(f fs.File, st *Stat_t) (err error)
• func ToPosixPath(in string) string
• func Unlink(name string) error
• func UnwrapOSError(err error) error
• func Utimens(path string, times *[2]syscall.Timespec, symlinkFollow bool) error
• func UtimensFile(f fs.File, times *[2]syscall.Timespec) error
• func Walltime() (sec int64, nsec int32)
• type Dirent
• func Readdir(f fs.File, n int) (dirents []*Dirent, err error)
• func (d *Dirent) IsDir() bool
• func (d *Dirent) String() string
• type File
• type PathFile
• type ReadFile
• type Stat_t

Constants ¶

const (
	// UTIME_NOW is a special syscall.Timespec NSec value used to set the
	// file's timestamp to a value close to, but not greater than the current
	// system time.
	UTIME_NOW = _UTIME_NOW

	// UTIME_OMIT is a special syscall.Timespec NSec value used to avoid
	// setting the file's timestamp.
	UTIME_OMIT = _UTIME_OMIT
)

const (
	O_DIRECTORY = 1 << 29
	O_NOFOLLOW  = 1 << 30
)

See the comments on the same constants in open_file_windows.go

const (

	// FakeEpochNanos is midnight UTC 2022-01-01 and exposed for testing
	FakeEpochNanos = 1640995200000 * ms
)

const (
	SupportsSymlinkNoFollow = false
)

Define values even if not used except as sentinels.

Variables ¶

var IsGo120 = strings.Contains(runtime.Version(), "go1.20")

TODO: IsAtLeastGo120

Functions ¶

func Chown ¶

func Chown(path string, uid, gid int) error

Chown is like os.Chown, except it returns a syscall.Errno, not a fs.PathError. For example, this returns syscall.ENOENT if the path doesn't exist. See https://linux.die.net/man/3/chown

Note: This always returns syscall.ENOSYS on windows.

func ChownFile ¶

func ChownFile(f fs.File, uid, gid int) error

ChownFile is like syscall.Fchown, but for nanosecond precision and fs.File instead of a file descriptor. This returns syscall.EBADF if the file or directory was closed. See https://linux.die.net/man/3/fchown

Note: This always returns syscall.ENOSYS on windows.

func CompilerSupported ¶

func CompilerSupported() bool

CompilerSupported is exported for tests and includes constraints here and also the assembler.

func FakeNanosleep ¶

func FakeNanosleep(int64)

FakeNanosleep implements sys.Nanosleep by returning without sleeping.

func FakeOsyield ¶

func FakeOsyield()

FakeOsyield implements sys.Osyield by returning without yielding.

func Fdatasync ¶

func Fdatasync(f fs.File) (err error)

Fdatasync is like syscall.Fdatasync except that's only defined in linux.

Note: This returns with no error instead of syscall.ENOSYS when unimplemented. This prevents fake filesystems from erring.

func IsTerminal ¶

func IsTerminal(fd uintptr) bool

IsTerminal returns true if the given file descriptor is a terminal.

func Lchown ¶

func Lchown(path string, uid, gid int) error

Lchown is like os.Lchown, except it returns a syscall.Errno, not a fs.PathError. For example, this returns syscall.ENOENT if the path doesn't exist. See https://linux.die.net/man/3/lchown

Note: This always returns syscall.ENOSYS on windows.

func Lstat ¶

func Lstat(path string, st *Stat_t) error

Lstat is like syscall.Lstat. This returns syscall.ENOENT if the path doesn't exist.

Notes

The primary difference between this and Stat is, when the path is a symbolic link, the stat is about the link, not its target, such as directory listings.

func MmapCodeSegment ¶

func MmapCodeSegment(code io.Reader, size int) ([]byte, error)

MmapCodeSegment copies the code into the executable region and returns the byte slice of the region.

See https://man7.org/linux/man-pages/man2/mmap.2.html for mmap API and flags.

func MunmapCodeSegment ¶

func MunmapCodeSegment(code []byte) error

MunmapCodeSegment unmaps the given memory region.

func Nanosleep ¶

func Nanosleep(ns int64)

Nanosleep implements sys.Nanosleep with time.Sleep.

func Nanotime ¶

func Nanotime() int64

Nanotime implements sys.Nanotime with runtime.nanotime() if CGO is available and time.Since if not.

func NewFakeNanotime ¶

func NewFakeNanotime() *sys.Nanotime

NewFakeNanotime implements sys.Nanotime that increases by 1ms each reading. See /RATIONALE.md

func NewFakeRandSource ¶

func NewFakeRandSource() io.Reader

NewFakeRandSource returns a deterministic source of random values.

func NewFakeWalltime ¶

func NewFakeWalltime() *sys.Walltime

NewFakeWalltime implements sys.Walltime with FakeEpochNanos that increases by 1ms each reading. See /RATIONALE.md

func OpenFile ¶

func OpenFile(name string, flag int, perm fs.FileMode) (f *os.File, err error)

func Readdirnames ¶

func Readdirnames(f fs.File, n int) (names []string, err error)

Readdirnames reads the names of the directory associated with file and returns a slice of up to n strings in an arbitrary order. This is a stateful function, so subsequent calls return any next values.

If n > 0, Readdirnames returns at most n entries or an error. If n <= 0, Readdirnames returns all remaining entries or an error.

Errors

If the error is non-nil, it is a syscall.Errno. io.EOF is not returned because implementations return that value inconsistently.

For portability reasons, no error is returned when the file is closed or removed while open. See https://github.com/ziglang/zig/blob/0.10.1/lib/std/fs.zig#L635-L637

func Rename ¶

func Rename(from, to string) error

func Stat ¶

func Stat(path string, st *Stat_t) error

Stat is like syscall.Stat. This returns syscall.ENOENT if the path doesn't exist.

func StatFile ¶

func StatFile(f fs.File, st *Stat_t) (err error)

StatFile is like syscall.Fstat, but for fs.File instead of a file descriptor. This returns syscall.EBADF if the file or directory was closed. Note: windows allows you to stat a closed directory.

func ToPosixPath ¶

func ToPosixPath(in string) string

ToPosixPath returns the input, as only windows might return backslashes.

func Unlink ¶

func Unlink(name string) error

func UnwrapOSError ¶

func UnwrapOSError(err error) error

UnwrapOSError returns a syscall.Errno or nil if the input is nil.

func Utimens ¶

func Utimens(path string, times *[2]syscall.Timespec, symlinkFollow bool) error

Utimens set file access and modification times on a path resolved to the current working directory, at nanosecond precision.

Parameters

The `times` parameter includes the access and modification timestamps to assign. Special syscall.Timespec NSec values UTIME_NOW and UTIME_OMIT may be specified instead of real timestamps. A nil `times` parameter behaves the same as if both were set to UTIME_NOW.

When the `symlinkFollow` parameter is true and the path is a symbolic link, the target of expanding that link is updated.

Errors

The following errors are expected:

• syscall.EINVAL: `path` is invalid.
• syscall.EEXIST: `path` exists and is a directory.
• syscall.ENOTDIR: `path` exists and is a file.

Notes

• This is similar to syscall.UtimesNano, except that doesn't have flags to control expansion of symbolic links. It also doesn't support special values UTIME_NOW or UTIME_NOW.
• This is like `utimensat` with `AT_FDCWD` in POSIX. See https://pubs.opengroup.org/onlinepubs/9699919799/functions/futimens.html

func UtimensFile ¶

func UtimensFile(f fs.File, times *[2]syscall.Timespec) error

UtimensFile is like Utimens, except it works on a file, not a path.

Notes

• Windows requires files to be open with syscall.O_RDWR, which means you cannot use this to update timestamps on a directory (syscall.EPERM).
• This is like the function `futimens` in POSIX. See https://pubs.opengroup.org/onlinepubs/9699919799/functions/futimens.html

func Walltime ¶

func Walltime() (sec int64, nsec int32)

Walltime implements sys.Walltime with time.Now.

Note: This is only notably less efficient than it could be is reading runtime.walltime(). time.Now defensively reads nanotime also, just in case time.Since is used. This doubles the performance impact. However, wall time is likely to be read less frequently than Nanotime. Also, doubling the cost matters less on fast platforms that can return both in <=100ns.

Types ¶

type Dirent ¶

type Dirent struct {

	// Name is the base name of the directory entry.
	Name string

	// Ino is the file serial number, or zero if not available.
	Ino uint64

	// Type is fs.FileMode masked on fs.ModeType. For example, zero is a
	// regular file, fs.ModeDir is a directory and fs.ModeIrregular is unknown.
	Type fs.FileMode
}

Dirent is an entry read from a directory.

This is a portable variant of syscall.Dirent containing fields needed for WebAssembly ABI including WASI snapshot-01 and wasi-filesystem. Unlike fs.DirEntry, this may include the Ino.

func Readdir ¶

func Readdir(f fs.File, n int) (dirents []*Dirent, err error)

Readdir reads the contents of the directory associated with file and returns a slice of up to n Dirent values in an arbitrary order. This is a stateful function, so subsequent calls return any next values.

If n > 0, Readdir returns at most n entries or an error. If n <= 0, Readdir returns all remaining entries or an error.

Errors

If the error is non-nil, it is a syscall.Errno. io.EOF is not returned because implementations return that value inconsistently.

For portability reasons, no error is returned when the file is closed or removed while open. See https://github.com/ziglang/zig/blob/0.10.1/lib/std/fs.zig#L635-L637

func (*Dirent) IsDir ¶

func (d *Dirent) IsDir() bool

IsDir returns true if the Type is fs.ModeDir.

func (*Dirent) String ¶

func (d *Dirent) String() string

type File ¶

type File interface {
	ReadFile
	io.Writer
	io.WriterAt // for pwrite
	// contains filtered or unexported methods
}

File declares all interfaces defined on os.File used by wazero.

type PathFile ¶

type PathFile interface {
	Path() string
}

PathFile is implemented on files that retain the path to their pre-open.

type ReadFile ¶

type ReadFile interface {
	fs.ReadDirFile
	io.ReaderAt // for pread
	io.Seeker   // fallback for ReaderAt for embed:fs
	// contains filtered or unexported methods
}

ReadFile declares all read interfaces defined on os.File used by wazero.

type Stat_t ¶

type Stat_t struct {
	// Dev is the device ID of device containing the file.
	Dev uint64

	// Ino is the file serial number.
	Ino uint64

	// Uid is the user ID that owns the file, or zero if unsupported.
	// For example, this is unsupported on some virtual filesystems or windows.
	Uid uint32

	// Gid is the group ID that owns the file, or zero if unsupported.
	// For example, this is unsupported on some virtual filesystems or windows.
	Gid uint32

	// Mode is the same as Mode on fs.FileInfo containing bits to identify the
	// type of the file (fs.ModeType) and its permissions (fs.ModePerm).
	Mode fs.FileMode

	/// Nlink is the number of hard links to the file.
	Nlink uint64

	// Size is the length in bytes for regular files. For symbolic links, this
	// is length in bytes of the pathname contained in the symbolic link.
	Size int64

	// Atim is the last data access timestamp in epoch nanoseconds.
	Atim int64

	// Mtim is the last data modification timestamp in epoch nanoseconds.
	Mtim int64

	// Ctim is the last file status change timestamp in epoch nanoseconds.
	Ctim int64
}

Stat_t is similar to syscall.Stat_t, and fields frequently used by WebAssembly ABI including WASI snapshot-01, GOOS=js and wasi-filesystem.

Note

Zero values may be returned where not available. For example, fs.FileInfo implementations may not be able to provide Ino values.

Source Files ¶

buf_writer.go chown.go chown_unix.go crypto.go dir.go errno.go error.go file.go futimens.go futimens_unsupported.go mmap_unsupported.go open_file_js.go path.go platform.go rename.go stat.go stat_unsupported.go sync.go sync_unsupported.go terminal_unsupported.go time.go time_cgo.go unlink.go