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) (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
- type File
- type PathFile
- type ReadFile
- type Stat_t
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 IsGo120 = strings.Contains(runtime.Version(), "go1.20")
TODO: IsAtLeastGo120
Functions ¶
func Chown ¶
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 ¶
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 ¶
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 ¶
IsTerminal returns true if the given file descriptor is a terminal.
func Lchown ¶
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 ¶
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 ¶
MunmapCodeSegment unmaps the given memory region.
func Nanotime ¶
func Nanotime() int64
Nanotime implements sys.Nanotime with runtime.nanotime() if CGO is available and time.Since if not.
func NewFakeNanotime ¶
NewFakeNanotime implements sys.Nanotime that increases by 1ms each reading. See /RATIONALE.md
func NewFakeRandSource ¶
NewFakeRandSource returns a deterministic source of random values.
func NewFakeWalltime ¶
NewFakeWalltime implements sys.Walltime with FakeEpochNanos that increases by 1ms each reading. See /RATIONALE.md
func Readdirnames ¶
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 ToPosixPath ¶
ToPosixPath returns the input, as only windows might return backslashes.
func UnwrapOSError ¶
UnwrapOSError returns a syscall.Errno or zero if the input is nil.
func Utimens ¶
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 ¶
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 ¶
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 ¶
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
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.
func Lstat ¶
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.
Source Files ¶
- buf_writer.go
- chown.go
- chown_unix.go
- cpuid_amd64.go
- crypto.go
- dir.go
- errno.go
- error.go
- file.go
- futimens.go
- futimens_darwin.go
- mmap.go
- open_file.go
- path.go
- platform.go
- platform_amd64.go
- rename.go
- stat.go
- stat_bsd.go
- sync.go
- sync_unsupported.go
- terminal.go
- terminal_bsd.go
- time.go
- time_cgo.go
- unlink.go