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 FakeNanosleep(int64)
• func FakeOsyield()
• func Fdatasync(f fs.File) syscall.Errno
• func IsTerminal(fd uintptr) bool
• func Lchown(path string, uid, gid int) syscall.Errno
• 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 Readdirnames(f fs.File, n int) (names []string, errno syscall.Errno)
• func Rename(from, to string) syscall.Errno
• func ToPosixPath(in string) string
• func Unlink(name string) 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 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 (
	// ERROR_ACCESS_DENIED is a Windows error returned by syscall.Unlink
	// instead of syscall.EPERM
	ERROR_ACCESS_DENIED = syscall.Errno(5)

	// ERROR_INVALID_HANDLE is a Windows error returned by syscall.Write
	// instead of syscall.EBADF
	ERROR_INVALID_HANDLE = syscall.Errno(6)

	// ERROR_FILE_EXISTS is a Windows error returned by os.OpenFile
	// instead of syscall.EEXIST
	ERROR_FILE_EXISTS = syscall.Errno(0x50)

	// ERROR_INVALID_NAME is a Windows error returned by open when a file
	// path has a trailing slash
	ERROR_INVALID_NAME = syscall.Errno(0x7B)

	// ERROR_NEGATIVE_SEEK is a Windows error returned by os.Truncate
	// instead of syscall.EINVAL
	ERROR_NEGATIVE_SEEK = syscall.Errno(0x83)

	// ERROR_DIR_NOT_EMPTY is a Windows error returned by syscall.Rmdir
	// instead of syscall.ENOTEMPTY
	ERROR_DIR_NOT_EMPTY = syscall.Errno(0x91)

	// ERROR_ALREADY_EXISTS is a Windows error returned by os.Mkdir
	// instead of syscall.EEXIST
	ERROR_ALREADY_EXISTS = syscall.Errno(0xB7)

	// ERROR_DIRECTORY is a Windows error returned by syscall.Rmdir
	// instead of syscall.ENOTDIR
	ERROR_DIRECTORY = syscall.Errno(0x10B)
)

See https://learn.microsoft.com/en-us/windows/win32/debug/system-error-codes--0-499-

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
)

Windows does not have these constants, we declare placeholders which should not conflict with other open flags. These placeholders are not declared as value zero so code written in a way which expects them to be bit flags still works as expected.

Since those placeholder are not interpreted by the open function, the unix features they represent are also not implemented on windows:

• O_DIRECTORY allows programs to ensure that the opened file is a directory. This could be emulated by doing a stat call on the file after opening it to verify that it is in fact a directory, then closing it and returning an error if it is not.

• O_NOFOLLOW allows programs to ensure that if the opened file is a symbolic link, the link itself is opened instead of its target.

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

const (
	// ERROR_PRIVILEGE_NOT_HELD is a Windows error returned by os.Symlink
	// instead of syscall.EPERM.
	//
	// Note: This can happen when trying to create symlinks w/o admin perms.
	ERROR_PRIVILEGE_NOT_HELD = syscall.Errno(0x522)
)

See https://learn.microsoft.com/en-us/windows/win32/debug/system-error-codes--1300-1699-

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) 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 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) 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 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) 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(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 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 ToPosixPath

func ToPosixPath(in string) string

ToPosixPath returns the input, converting any backslashes to forward ones.

func Unlink

func Unlink(name string) 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 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)

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.