platform

Documentation

Overview

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) syscall.Errno
• func ChownFile(f fs.File, uid, gid int) syscall.Errno
• func CompilerSupported() bool
• func Fdatasync(f fs.File) syscall.Errno
• func Lchown(path string, uid, gid int) syscall.Errno
• func MmapCodeSegment(size int) ([]byte, error)
• func MprotectRX(b []byte) (err 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 Readdirnames(f fs.File, n int) (names []string, errno syscall.Errno)
• func Rename(from, to string) syscall.Errno
• func Select(n int, r, w, e *FdSet, timeout *time.Duration) (int, error)
• func ToPosixPath(in string) string
• func Unlink(name string) (errno syscall.Errno)
• func UnwrapOSError(err error) syscall.Errno
• func Utimens(path string, times *[2]syscall.Timespec, symlinkFollow bool) syscall.Errno
• func UtimensFile(f fs.File, times *[2]syscall.Timespec) syscall.Errno
• func Walltime() (sec int64, nsec int32)
• type CpuFeatureFlags
• type Dirent
  • func Readdir(f fs.File, n int) (dirents []*Dirent, errno syscall.Errno)
  • func (d *Dirent) IsDir() bool
  • func (d *Dirent) String() string
• type FdSet
  • func (f *FdSet) Clear(fd int)
  • func (f *FdSet) IsSet(fd int) bool
  • func (f *FdSet) Set(fd int)
  • func (f *FdSet) Zero()
• type File
  • func OpenFile(path string, flag int, perm fs.FileMode) (File, syscall.Errno)
• type PathFile
• type ReadFile
• type Stat_t
  • func Lstat(path string) (Stat_t, syscall.Errno)
  • func Stat(path string) (Stat_t, syscall.Errno)
  • func StatFile(f fs.File) (Stat_t, syscall.Errno)

Constants

const (
	// CpuFeatureSSE3 is the flag to query CpuFeatureFlags.Has for SSEv3 capabilities
	CpuFeatureSSE3 = uint64(1)
	// CpuFeatureSSE4_1 is the flag to query CpuFeatureFlags.Has for SSEv4.1 capabilities
	CpuFeatureSSE4_1 = uint64(1) << 19
	// CpuFeatureSSE4_2 is the flag to query CpuFeatureFlags.Has for SSEv4.2 capabilities
	CpuFeatureSSE4_2 = uint64(1) << 20
)

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 = syscall.O_DIRECTORY
	O_NOFOLLOW  = syscall.O_NOFOLLOW
)

Simple aliases to constants in the syscall package for portability with platforms which do not have them (e.g. windows)

const (
	// CpuExtraFeatureABM is the flag to query CpuFeatureFlags.HasExtra for Advanced Bit Manipulation capabilities (e.g. LZCNT)
	CpuExtraFeatureABM = uint64(1) << 5
)

const (

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

const (
	SupportsSymlinkNoFollow = true
)

Variables

var FakeNanosleep = sys.Nanosleep(func(int64) {})

FakeNanosleep implements sys.Nanosleep by returning without sleeping.

var FakeOsyield = sys.Osyield(func() {})

FakeOsyield implements sys.Osyield by returning without yielding.

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

TODO: IsAtLeastGo120

Functions

func Chown

func Chown(path string, uid, gid int) syscall.Errno

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. A syscall.Errno of zero is success.

Note: This always returns syscall.ENOSYS on windows. See https://linux.die.net/man/3/chown

func ChownFile

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

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 Fdatasync

func Fdatasync(f fs.File) syscall.Errno

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 Lchown

func Lchown(path string, uid, gid int) syscall.Errno

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. A syscall.Errno of zero is success.

Note: This always returns syscall.ENOSYS on windows. See https://linux.die.net/man/3/lchown

func MmapCodeSegment

func MmapCodeSegment(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 MprotectRX

func MprotectRX(b []byte) (err error)

MprotectRX is like syscall.Mprotect, defined locally so that freebsd compiles.

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 Readdirnames

func Readdirnames(f fs.File, n int) (names []string, errno syscall.Errno)

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

A zero syscall.Errno is success.

For portability reasons, no error is returned on io.EOF, 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) syscall.Errno

func Select

func Select(n int, r, w, e *FdSet, timeout *time.Duration) (int, error)

Select exposes the select(2) syscall.

Notes on Parameters

For convenience, we expose a pointer to a time.Duration instead of a pointer to a syscall.Timeval.
It must be a pointer because `nil` means "wait forever".

However, notice that select(2) may mutate the pointed Timeval on some platforms,
for instance if the call returns early.

This implementation *will not* update the pointed time.Duration value accordingly.

See also: https://github.com/golang/sys/blob/master/unix/syscall_unix_test.go#L606-L617

Notes on the Syscall

Because this is a blocking syscall, it will also block the carrier thread of the goroutine,
preventing any means to support context cancellation directly.

There are ways to obviate this issue. We outline here one idea, that is however not currently implemented.
A common approach to support context cancellation is to add a signal file descriptor to the set,
e.g. the read-end of a pipe or an eventfd on Linux.
When the context is canceled, we may unblock a Select call by writing to the fd, causing it to return immediately.
This however requires to do a bit of housekeeping to hide the "special" FD from the end-user.

func ToPosixPath

func ToPosixPath(in string) string

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

func Unlink

func Unlink(name string) (errno syscall.Errno)

func UnwrapOSError

func UnwrapOSError(err error) syscall.Errno

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

func Utimens

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

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) syscall.Errno

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 CpuFeatureFlags

type CpuFeatureFlags interface {
	// Has returns true when the specified flag (represented as uint64) is supported
	Has(cpuFeature uint64) bool
	// HasExtra returns true when the specified extraFlag (represented as uint64) is supported
	HasExtra(cpuFeature uint64) bool
}

CpuFeatureFlags exposes methods for querying CPU capabilities

var CpuFeatures CpuFeatureFlags = loadCpuFeatureFlags()

CpuFeatures exposes the capabilities for this CPU, queried via the Has, HasExtra methods

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, errno syscall.Errno)

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

A zero syscall.Errno is success.

For portability reasons, no error is returned on io.EOF, 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 FdSet

type FdSet syscall.FdSet

FdSet re-exports syscall.FdSet with utility methods.

func (*FdSet) Clear

func (f *FdSet) Clear(fd int)

Clear removes the given fd from the set.

func (*FdSet) IsSet

func (f *FdSet) IsSet(fd int) bool

IsSet returns true when fd is in the set.

func (*FdSet) Set

func (f *FdSet) Set(fd int)

Set adds the given fd to the set.

func (*FdSet) Zero

func (f *FdSet) Zero()

Zero clears the set.

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.

func OpenFile

func OpenFile(path string, flag int, perm fs.FileMode) (File, syscall.Errno)

OpenFile is like os.OpenFile except it returns syscall.Errno. A zero syscall.Errno is success.

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.

func Lstat

func Lstat(path string) (Stat_t, syscall.Errno)

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 Stat

func Stat(path string) (Stat_t, syscall.Errno)

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

func StatFile

func StatFile(f fs.File) (Stat_t, syscall.Errno)

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.