sys

package
v1.5.0 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2023 License: Apache-2.0 Imports: 8 Imported by: 11

Documentation

Index

Constants

View Source 
const UTIME_OMIT int64 = math.MinInt64

UTIME_OMIT is a special constant for use in updating times via FS.Utimens or File.Utimens. When used for atim or mtim, the value is retained.

Note: This may be implemented via a stat when the underlying filesystem does not support this value.

Variables

This section is empty.

Functions

This section is empty.

Types

type DirFile added in v1.4.0 

type DirFile struct{}

DirFile is embeddable to reduce the amount of functions to implement a file.

func (DirFile) IsAppend added in v1.4.0 

func (DirFile) IsAppend() bool

IsAppend implements File.IsAppend

func (DirFile) IsDir added in v1.4.0 

func (DirFile) IsDir() (bool, Errno)

IsDir implements File.IsDir

func (DirFile) Pread added in v1.4.0 

func (DirFile) Pread([]byte, int64) (int, Errno)

Pread implements File.Pread

func (DirFile) Pwrite added in v1.4.0 

func (DirFile) Pwrite([]byte, int64) (int, Errno)

Pwrite implements File.Pwrite

func (DirFile) Read added in v1.4.0 

func (DirFile) Read([]byte) (int, Errno)

Read implements File.Read

func (DirFile) SetAppend added in v1.4.0 

func (DirFile) SetAppend(bool) Errno

SetAppend implements File.SetAppend

func (DirFile) Truncate added in v1.4.0 

func (DirFile) Truncate(int64) Errno

Truncate implements File.Truncate

func (DirFile) Write added in v1.4.0 

func (DirFile) Write([]byte) (int, Errno)

Write implements File.Write

type Dirent added in v1.4.0 

type Dirent struct {
	// Ino is the file serial number, or zero if not available. See Ino for
	// more details including impact returning a zero value.
	Ino sys.Inode

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

	// 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.
	//
	// Note: This is defined by Linux, not POSIX.
	Type fs.FileMode
}

Dirent is an entry read from a directory via File.Readdir.

Notes

func (*Dirent) IsDir added in v1.4.0 

func (d *Dirent) IsDir() bool

IsDir returns true if the Type is fs.ModeDir.

func (*Dirent) String added in v1.4.0 

func (d *Dirent) String() string

type Errno 

type Errno uint16

Errno is a subset of POSIX errno used by wazero interfaces. Zero is not an error. Other values should not be interpreted numerically, rather by constants prefixed with 'E'.

See https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/errno.h.html 

const (
	EACCES Errno = iota + 1
	EAGAIN
	EBADF
	EEXIST
	EFAULT
	EINTR
	EINVAL
	EIO
	EISDIR
	ELOOP
	ENAMETOOLONG
	ENOENT
	ENOSYS
	ENOTDIR
	ERANGE
	ENOTEMPTY
	ENOTSOCK
	ENOTSUP
	EPERM
	EROFS
)

This is a subset of errors to reduce implementation burden. `wasip1` defines almost all POSIX error numbers, but not all are used in practice. wazero will add ones needed in POSIX order, as needed by functions that explicitly document returning them.

https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md#-errno-enumu16

func UnwrapOSError 

func UnwrapOSError(err error) Errno

UnwrapOSError returns an Errno or zero if the input is nil.

func (Errno) Error 

func (e Errno) Error() string

Error implements error

func (Errno) Unwrap 

func (e Errno) Unwrap() error

Unwrap is a convenience for runtime.GOOS which define syscall.Errno.

type FS added in v1.4.0 

type FS interface {
	// OpenFile opens a file. It should be closed via Close on File.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EINVAL: `path` or `flag` is invalid.
	//   - EISDIR: the path was a directory, but flag included O_RDWR or
	//     O_WRONLY
	//   - ENOENT: `path` doesn't exist and `flag` doesn't contain O_CREAT.
	//
	// # Constraints on the returned file
	//
	// Implementations that can read flags should enforce them regardless of
	// the type returned. For example, while os.File implements io.Writer,
	// attempts to write to a directory or a file opened with O_RDONLY fail
	// with a EBADF.
	//
	// Some implementations choose whether to enforce read-only opens, namely
	// fs.FS. While fs.FS is supported (Adapt), wazero cannot runtime enforce
	// open flags. Instead, we encourage good behavior and test our built-in
	// implementations.
	//
	// # Notes
	//
	//   - This is like os.OpenFile, except the path is relative to this file
	//     system, and Errno is returned instead of os.PathError.
	//   - Implications of permissions when O_CREAT are described in Chmod notes.
	//   - This is like `open` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/open.html
	OpenFile(path string, flag Oflag, perm fs.FileMode) (File, Errno)

	// Lstat gets file status without following symbolic links.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - ENOENT: `path` doesn't exist.
	//
	// # Notes
	//
	//   - This is like syscall.Lstat, except the `path` is relative to this
	//     file system.
	//   - This is like `lstat` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/lstat.html
	//   - An fs.FileInfo backed implementation sets atim, mtim and ctim to the
	//     same value.
	//   - When the path is a symbolic link, the stat returned is for the link,
	//     not the file it refers to.
	Lstat(path string) (sys.Stat_t, Errno)

	// Stat gets file status.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - ENOENT: `path` doesn't exist.
	//
	// # Notes
	//
	//   - This is like syscall.Stat, except the `path` is relative to this
	//     file system.
	//   - This is like `stat` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/stat.html
	//   - An fs.FileInfo backed implementation sets atim, mtim and ctim to the
	//     same value.
	//   - When the path is a symbolic link, the stat returned is for the file
	//     it refers to.
	Stat(path string) (sys.Stat_t, Errno)

	// Mkdir makes a directory.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EINVAL: `path` is invalid.
	//   - EEXIST: `path` exists and is a directory.
	//   - ENOTDIR: `path` exists and is a file.
	//
	// # Notes
	//
	//   - This is like syscall.Mkdir, except the `path` is relative to this
	//     file system.
	//   - This is like `mkdir` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/mkdir.html
	//   - Implications of permissions are described in Chmod notes.
	Mkdir(path string, perm fs.FileMode) Errno

	// Chmod changes the mode of the file.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EINVAL: `path` is invalid.
	//   - ENOENT: `path` does not exist.
	//
	// # Notes
	//
	//   - This is like syscall.Chmod, except the `path` is relative to this
	//     file system.
	//   - This is like `chmod` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/chmod.html
	//   - Windows ignores the execute bit, and any permissions come back as
	//     group and world. For example, chmod of 0400 reads back as 0444, and
	//     0700 0666. Also, permissions on directories aren't supported at all.
	Chmod(path string, perm fs.FileMode) Errno

	// Rename renames file or directory.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EINVAL: `from` or `to` is invalid.
	//   - ENOENT: `from` or `to` don't exist.
	//   - ENOTDIR: `from` is a directory and `to` exists as a file.
	//   - EISDIR: `from` is a file and `to` exists as a directory.
	//   - ENOTEMPTY: `both from` and `to` are existing directory, but
	//    `to` is not empty.
	//
	// # Notes
	//
	//   - This is like syscall.Rename, except the paths are relative to this
	//     file system.
	//   - This is like `rename` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/rename.html
	//   -  Windows doesn't let you overwrite an existing directory.
	Rename(from, to string) Errno

	// Rmdir removes a directory.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EINVAL: `path` is invalid.
	//   - ENOENT: `path` doesn't exist.
	//   - ENOTDIR: `path` exists, but isn't a directory.
	//   - ENOTEMPTY: `path` exists, but isn't empty.
	//
	// # Notes
	//
	//   - This is like syscall.Rmdir, except the `path` is relative to this
	//     file system.
	//   - This is like `rmdir` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/rmdir.html
	//   - As of Go 1.19, Windows maps ENOTDIR to ENOENT.
	Rmdir(path string) Errno

	// Unlink removes a directory entry.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EINVAL: `path` is invalid.
	//   - ENOENT: `path` doesn't exist.
	//   - EISDIR: `path` exists, but is a directory.
	//
	// # Notes
	//
	//   - This is like syscall.Unlink, except the `path` is relative to this
	//     file system.
	//   - This is like `unlink` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/unlink.html
	//   - On Windows, syscall.Unlink doesn't delete symlink to directory unlike other platforms. Implementations might
	//     want to combine syscall.RemoveDirectory with syscall.Unlink in order to delete such links on Windows.
	//     See https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-removedirectorya
	Unlink(path string) Errno

	// Link creates a "hard" link from oldPath to newPath, in contrast to a
	// soft link (via Symlink).
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EPERM: `oldPath` is invalid.
	//   - ENOENT: `oldPath` doesn't exist.
	//   - EISDIR: `newPath` exists, but is a directory.
	//
	// # Notes
	//
	//   - This is like syscall.Link, except the `oldPath` is relative to this
	//     file system.
	//   - This is like `link` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/link.html
	Link(oldPath, newPath string) Errno

	// Symlink creates a "soft" link from oldPath to newPath, in contrast to a
	// hard link (via Link).
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EPERM: `oldPath` or `newPath` is invalid.
	//   - EEXIST: `newPath` exists.
	//
	// # Notes
	//
	//   - This is like syscall.Symlink, except the `oldPath` is relative to
	//     this file system.
	//   - This is like `symlink` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/symlink.html
	//   - Only `newPath` is relative to this file system and `oldPath` is kept
	//     as-is. That is because the link is only resolved relative to the
	//     directory when dereferencing it (e.g. ReadLink).
	//     See https://github.com/bytecodealliance/cap-std/blob/v1.0.4/cap-std/src/fs/dir.rs#L404-L409
	//     for how others implement this.
	//   - Symlinks in Windows requires `SeCreateSymbolicLinkPrivilege`.
	//     Otherwise, EPERM results.
	//     See https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links
	Symlink(oldPath, linkName string) Errno

	// Readlink reads the contents of a symbolic link.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EINVAL: `path` is invalid.
	//
	// # Notes
	//
	//   - This is like syscall.Readlink, except the path is relative to this
	//     filesystem.
	//   - This is like `readlink` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/readlink.html
	//   - On Windows, the path separator is different from other platforms,
	//     but to provide consistent results to Wasm, this normalizes to a "/"
	//     separator.
	Readlink(path string) (string, Errno)

	// Utimens set file access and modification times on a path relative to
	// this file system, at nanosecond precision.
	//
	// # Parameters
	//
	// If the path is a symbolic link, the target of expanding that link is
	// updated.
	//
	// The `atim` and `mtim` parameters refer to access and modification time
	// stamps as defined in sys.Stat_t. To retain one or the other, substitute
	// it with the pseudo-timestamp UTIME_OMIT.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EINVAL: `path` is invalid.
	//   - EEXIST: `path` exists and is a directory.
	//   - ENOTDIR: `path` exists and is a file.
	//
	// # Notes
	//
	//   - This is like syscall.UtimesNano and `utimensat` with `AT_FDCWD` in
	//     POSIX. See https://pubs.opengroup.org/onlinepubs/9699919799/functions/futimens.html
	Utimens(path string, atim, mtim int64) Errno
}

FS is a writeable fs.FS bridge backed by syscall functions needed for ABI including WASI and runtime.GOOS=js.

Implementations should embed UnimplementedFS for forward compatability. Any unsupported method or parameter should return ENO

Errors

All methods that can return an error return a Errno, which is zero on success.

Restricting to Errno matches current WebAssembly host functions, which are constrained to well-known error codes. For example, `GOOS=js` maps hard coded values and panics otherwise. More commonly, WASI maps syscall errors to u32 numeric values.

Notes

A writable filesystem abstraction is not yet implemented as of Go 1.20. See https://github.com/golang/go/issues/45757

type File added in v1.4.0 

type File interface {
	// Dev returns the device ID (Stat_t.Dev) of this file, zero if unknown or
	// an error retrieving it.
	//
	// # Errors
	//
	// Possible errors are those from Stat, except ENOSYS should not
	// be returned. Zero should be returned if there is no implementation.
	//
	// # Notes
	//
	//   - Implementations should cache this result.
	//   - This combined with Ino can implement os.SameFile.
	Dev() (uint64, Errno)

	// Ino returns the serial number (Stat_t.Ino) of this file, zero if unknown
	// or an error retrieving it.
	//
	// # Errors
	//
	// Possible errors are those from Stat, except ENOSYS should not
	// be returned. Zero should be returned if there is no implementation.
	//
	// # Notes
	//
	//   - Implementations should cache this result.
	//   - This combined with Dev can implement os.SameFile.
	Ino() (sys.Inode, Errno)

	// IsDir returns true if this file is a directory or an error there was an
	// error retrieving this information.
	//
	// # Errors
	//
	// Possible errors are those from Stat, except ENOSYS should not
	// be returned. false should be returned if there is no implementation.
	//
	// # Notes
	//
	//   - Implementations should cache this result.
	IsDir() (bool, Errno)

	// IsAppend returns true if the file was opened with O_APPEND, or
	// SetAppend was successfully enabled on this file.
	//
	// # Notes
	//
	//   - This might not match the underlying state of the file descriptor if
	//     the file was not opened via OpenFile.
	IsAppend() bool

	// SetAppend toggles the append mode (O_APPEND) of this file.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EBADF: the file or directory was closed.
	//
	// # Notes
	//
	//   - There is no `O_APPEND` for `fcntl` in POSIX, so implementations may
	//     have to re-open the underlying file to apply this. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/open.html
	SetAppend(enable bool) Errno

	// Stat is similar to syscall.Fstat.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EBADF: the file or directory was closed.
	//
	// # Notes
	//
	//   - This is like syscall.Fstat and `fstatat` with `AT_FDCWD` in POSIX.
	//     See https://pubs.opengroup.org/onlinepubs/9699919799/functions/stat.html
	//   - A fs.FileInfo backed implementation sets atim, mtim and ctim to the
	//     same value.
	//   - Windows allows you to stat a closed directory.
	Stat() (sys.Stat_t, Errno)

	// Read attempts to read all bytes in the file into `buf`, and returns the
	// count read even on error.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EBADF: the file or directory was closed or not readable.
	//   - EISDIR: the file was a directory.
	//
	// # Notes
	//
	//   - This is like io.Reader and `read` in POSIX, preferring semantics of
	//     io.Reader. See https://pubs.opengroup.org/onlinepubs/9699919799/functions/read.html
	//   - Unlike io.Reader, there is no io.EOF returned on end-of-file. To
	//     read the file completely, the caller must repeat until `n` is zero.
	Read(buf []byte) (n int, errno Errno)

	// Pread attempts to read all bytes in the file into `p`, starting at the
	// offset `off`, and returns the count read even on error.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EBADF: the file or directory was closed or not readable.
	//   - EINVAL: the offset was negative.
	//   - EISDIR: the file was a directory.
	//
	// # Notes
	//
	//   - This is like io.ReaderAt and `pread` in POSIX, preferring semantics
	//     of io.ReaderAt. See https://pubs.opengroup.org/onlinepubs/9699919799/functions/pread.html
	//   - Unlike io.ReaderAt, there is no io.EOF returned on end-of-file. To
	//     read the file completely, the caller must repeat until `n` is zero.
	Pread(buf []byte, off int64) (n int, errno Errno)

	// Seek attempts to set the next offset for Read or Write and returns the
	// resulting absolute offset or an error.
	//
	// # Parameters
	//
	// The `offset` parameters is interpreted in terms of `whence`:
	//   - io.SeekStart: relative to the start of the file, e.g. offset=0 sets
	//     the next Read or Write to the beginning of the file.
	//   - io.SeekCurrent: relative to the current offset, e.g. offset=16 sets
	//     the next Read or Write 16 bytes past the prior.
	//   - io.SeekEnd: relative to the end of the file, e.g. offset=-1 sets the
	//     next Read or Write to the last byte in the file.
	//
	// # Behavior when a directory
	//
	// The only supported use case for a directory is seeking to `offset` zero
	// (`whence` = io.SeekStart). This should have the same behavior as
	// os.File, which resets any internal state used by Readdir.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EBADF: the file or directory was closed or not readable.
	//   - EINVAL: the offset was negative.
	//
	// # Notes
	//
	//   - This is like io.Seeker and `fseek` in POSIX, preferring semantics
	//     of io.Seeker. See https://pubs.opengroup.org/onlinepubs/9699919799/functions/fseek.html
	Seek(offset int64, whence int) (newOffset int64, errno 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 Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EBADF: the file was closed or not a directory.
	//   - ENOENT: the directory could not be read (e.g. deleted).
	//
	// # Notes
	//
	//   - This is like `Readdir` on os.File, but unlike `readdir` in POSIX.
	//     See https://pubs.opengroup.org/onlinepubs/9699919799/functions/readdir.html
	//   - Unlike os.File, there is no io.EOF returned on end-of-directory. To
	//     read the directory completely, the caller must repeat until the
	//     count read (`len(dirents)`) is less than `n`.
	//   - See /RATIONALE.md for design notes.
	Readdir(n int) (dirents []Dirent, errno Errno)

	// Write attempts to write all bytes in `p` to the file, and returns the
	// count written even on error.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EBADF: the file was closed, not writeable, or a directory.
	//
	// # Notes
	//
	//   - This is like io.Writer and `write` in POSIX, preferring semantics of
	//     io.Writer. See https://pubs.opengroup.org/onlinepubs/9699919799/functions/write.html
	Write(buf []byte) (n int, errno Errno)

	// Pwrite attempts to write all bytes in `p` to the file at the given
	// offset `off`, and returns the count written even on error.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EBADF: the file or directory was closed or not writeable.
	//   - EINVAL: the offset was negative.
	//   - EISDIR: the file was a directory.
	//
	// # Notes
	//
	//   - This is like io.WriterAt and `pwrite` in POSIX, preferring semantics
	//     of io.WriterAt. See https://pubs.opengroup.org/onlinepubs/9699919799/functions/pwrite.html
	Pwrite(buf []byte, off int64) (n int, errno Errno)

	// Truncate truncates a file to a specified length.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EBADF: the file or directory was closed.
	//   - EINVAL: the `size` is negative.
	//   - EISDIR: the file was a directory.
	//
	// # Notes
	//
	//   - This is like syscall.Ftruncate and `ftruncate` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/ftruncate.html
	//   - Windows does not error when calling Truncate on a closed file.
	Truncate(size int64) Errno

	// Sync synchronizes changes to the file.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - EBADF: the file or directory was closed.
	//
	// # Notes
	//
	//   - This is like syscall.Fsync and `fsync` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/fsync.html
	//   - This returns with no error instead of ENOSYS when
	//     unimplemented. This prevents fake filesystems from erring.
	//   - Windows does not error when calling Sync on a closed file.
	Sync() Errno

	// Datasync synchronizes the data of a file.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - EBADF: the file or directory was closed.
	//
	// # Notes
	//
	//   - This is like syscall.Fdatasync and `fdatasync` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/fdatasync.html
	//   - This returns with no error instead of ENOSYS when
	//     unimplemented. This prevents fake filesystems from erring.
	//   - As this is commonly missing, some implementations dispatch to Sync.
	Datasync() Errno

	// Utimens set file access and modification times of this file, at
	// nanosecond precision.
	//
	// # Parameters
	//
	// The `atim` and `mtim` parameters refer to access and modification time
	// stamps as defined in sys.Stat_t. To retain one or the other, substitute
	// it with the pseudo-timestamp UTIME_OMIT.
	//
	// # Errors
	//
	// A zero Errno is success. The below are expected otherwise:
	//   - ENOSYS: the implementation does not support this function.
	//   - EBADF: the file or directory was closed.
	//
	// # Notes
	//
	//   - This is like syscall.UtimesNano and `futimens` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/futimens.html
	//   - Windows requires files to be open with O_RDWR, which means you
	//     cannot use this to update timestamps on a directory (EPERM).
	Utimens(atim, mtim int64) Errno

	// Close closes the underlying file.
	//
	// A zero Errno is returned if unimplemented or success.
	//
	// # Notes
	//
	//   - This is like syscall.Close and `close` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/close.html
	Close() Errno
}

File is a writeable fs.File bridge backed by syscall functions needed for ABI including WASI and runtime.GOOS=js.

Implementations should embed UnimplementedFile for forward compatability. Any unsupported method or parameter should return ENOSYS.

Errors

All methods that can return an error return a Errno, which is zero on success.

Restricting to Errno matches current WebAssembly host functions, which are constrained to well-known error codes. For example, `GOOS=js` maps hard coded values and panics otherwise. More commonly, WASI maps syscall errors to u32 numeric values.

Notes

  • You must call Close to avoid file resource conflicts. For example, Windows cannot delete the underlying directory while a handle to it remains open.
  • A writable filesystem abstraction is not yet implemented as of Go 1.20. See https://github.com/golang/go/issues/45757

type FileType added in v1.4.0 

type FileType = fs.FileMode

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

Note: This is defined by Linux, not POSIX.

type Oflag added in v1.4.0 

type Oflag uint32

Oflag are flags used for FS.OpenFile. Values, including zero, should not be interpreted numerically. Instead, use by constants prefixed with 'O_' with special casing noted below.

Notes 

const (
	// O_RDONLY is like os.O_RDONLY
	O_RDONLY Oflag = iota

	// O_RDWR is like os.O_RDWR
	O_RDWR

	// O_WRONLY is like os.O_WRONLY
	O_WRONLY

	// O_APPEND is like os.O_APPEND
	O_APPEND Oflag = 1 << iota

	// O_CREAT is link os.O_CREATE
	O_CREAT

	// O_DIRECTORY is defined on some platforms as syscall.O_DIRECTORY.
	//
	// Note: This ensures that the opened file is a directory. Those emulating
	// on platforms that don't support the O_DIRECTORY, can double-check the
	// result with File.IsDir (or stat) and err if not a directory.
	O_DIRECTORY

	// O_DSYNC is defined on some platforms as syscall.O_DSYNC.
	O_DSYNC

	// O_EXCL is defined on some platforms as syscall.O_EXCL.
	O_EXCL

	// O_NOFOLLOW is defined on some platforms as syscall.O_NOFOLLOW.
	//
	// Note: This allows programs to ensure that if the opened file is a
	// symbolic link, the link itself is opened instead of its target.
	O_NOFOLLOW

	// O_NONBLOCK is defined on some platforms as syscall.O_NONBLOCK.
	O_NONBLOCK

	// O_RSYNC is defined on some platforms as syscall.O_RSYNC.
	O_RSYNC

	// O_SYNC is defined on some platforms as syscall.O_SYNC.
	O_SYNC

	// O_TRUNC is defined on some platforms as syscall.O_TRUNC.
	O_TRUNC
)

This is a subset of oflags to reduce implementation burden. `wasip1` splits these across `oflags` and `fdflags`. We can't rely on the Go `os` package, as it is missing some values. Any flags added will be defined in POSIX order, as needed by functions that explicitly document accepting them.

https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md#-oflags-flagsu16 https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md#-fdflags-flagsu16

type UnimplementedFS added in v1.4.0 

type UnimplementedFS struct{}

UnimplementedFS is an FS that returns ENOSYS for all functions, This should be embedded to have forward compatible implementations.

func (UnimplementedFS) Chmod added in v1.4.0 

func (UnimplementedFS) Chmod(path string, perm fs.FileMode) Errno

Chmod implements FS.Chmod 

func (UnimplementedFS) Link(_, _ string) Errno

Link implements FS.Link

func (UnimplementedFS) Lstat added in v1.4.0 

func (UnimplementedFS) Lstat(path string) (sys.Stat_t, Errno)

Lstat implements FS.Lstat

func (UnimplementedFS) Mkdir added in v1.4.0 

func (UnimplementedFS) Mkdir(path string, perm fs.FileMode) Errno

Mkdir implements FS.Mkdir

func (UnimplementedFS) OpenFile added in v1.4.0 

func (UnimplementedFS) OpenFile(path string, flag Oflag, perm fs.FileMode) (File, Errno)

OpenFile implements FS.OpenFile 

func (UnimplementedFS) Readlink(path string) (string, Errno)

Readlink implements FS.Readlink

func (UnimplementedFS) Rename added in v1.4.0 

func (UnimplementedFS) Rename(from, to string) Errno

Rename implements FS.Rename

func (UnimplementedFS) Rmdir added in v1.4.0 

func (UnimplementedFS) Rmdir(path string) Errno

Rmdir implements FS.Rmdir

func (UnimplementedFS) Stat added in v1.4.0 

func (UnimplementedFS) Stat(path string) (sys.Stat_t, Errno)

Stat implements FS.Stat 

func (UnimplementedFS) Symlink(_, _ string) Errno

Symlink implements FS.Symlink 

func (UnimplementedFS) Unlink(path string) Errno

Unlink implements FS.Unlink

func (UnimplementedFS) Utimens added in v1.4.0 

func (UnimplementedFS) Utimens(path string, atim, mtim int64) Errno

Utimens implements FS.Utimens

type UnimplementedFile added in v1.4.0 

type UnimplementedFile struct{}

UnimplementedFile is a File that returns ENOSYS for all functions, except where no-op are otherwise documented.

This should be embedded to have forward compatible implementations.

func (UnimplementedFile) Close added in v1.4.0 

func (UnimplementedFile) Close() (errno Errno)

Close implements File.Close

func (UnimplementedFile) Datasync added in v1.4.0 

func (UnimplementedFile) Datasync() Errno

Datasync implements File.Datasync

func (UnimplementedFile) Dev added in v1.4.0 

func (UnimplementedFile) Dev() (uint64, Errno)

Dev implements File.Dev

func (UnimplementedFile) Ino added in v1.4.0 

func (UnimplementedFile) Ino() (sys.Inode, Errno)

Ino implements File.Ino

func (UnimplementedFile) IsAppend added in v1.4.0 

func (UnimplementedFile) IsAppend() bool

IsAppend implements File.IsAppend

func (UnimplementedFile) IsDir added in v1.4.0 

func (UnimplementedFile) IsDir() (bool, Errno)

IsDir implements File.IsDir

func (UnimplementedFile) Pread added in v1.4.0 

func (UnimplementedFile) Pread([]byte, int64) (int, Errno)

Pread implements File.Pread

func (UnimplementedFile) Pwrite added in v1.4.0 

func (UnimplementedFile) Pwrite([]byte, int64) (int, Errno)

Pwrite implements File.Pwrite

func (UnimplementedFile) Read added in v1.4.0 

func (UnimplementedFile) Read([]byte) (int, Errno)

Read implements File.Read

func (UnimplementedFile) Readdir added in v1.4.0 

func (UnimplementedFile) Readdir(int) (dirents []Dirent, errno Errno)

Readdir implements File.Readdir

func (UnimplementedFile) Seek added in v1.4.0 

func (UnimplementedFile) Seek(int64, int) (int64, Errno)

Seek implements File.Seek

func (UnimplementedFile) SetAppend added in v1.4.0 

func (UnimplementedFile) SetAppend(bool) Errno

SetAppend implements File.SetAppend

func (UnimplementedFile) Stat added in v1.4.0 

func (UnimplementedFile) Stat() (sys.Stat_t, Errno)

Stat implements File.Stat

func (UnimplementedFile) Sync added in v1.4.0 

func (UnimplementedFile) Sync() Errno

Sync implements File.Sync

func (UnimplementedFile) Truncate added in v1.4.0 

func (UnimplementedFile) Truncate(int64) Errno

Truncate implements File.Truncate

func (UnimplementedFile) Utimens added in v1.4.0 

func (UnimplementedFile) Utimens(int64, int64) Errno

Utimens implements File.Utimens

func (UnimplementedFile) Write added in v1.4.0 

func (UnimplementedFile) Write([]byte) (int, Errno)

Write implements File.Write

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.