fsapi

package
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Jun 2, 2023 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	O_DIRECTORY = syscall.O_DIRECTORY
	O_NOFOLLOW  = syscall.O_NOFOLLOW
	O_NONBLOCK  = syscall.O_NONBLOCK
)

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

Variables

This section is empty.

Functions

This section is empty.

Types

type DirFile 

type DirFile struct{}

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

func (DirFile) IsAppend 

func (DirFile) IsAppend() bool

IsAppend implements File.IsAppend

func (DirFile) IsDir 

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

IsDir implements File.IsDir

func (DirFile) IsNonblock 

func (DirFile) IsNonblock() bool

IsNonblock implements File.IsNonblock

func (DirFile) PollRead 

func (DirFile) PollRead(*time.Duration) (ready bool, errno syscall.Errno)

PollRead implements File.PollRead

func (DirFile) Pread 

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

Pread implements File.Pread

func (DirFile) Pwrite 

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

Pwrite implements File.Pwrite

func (DirFile) Read 

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

Read implements File.Read

func (DirFile) Seek 

func (DirFile) Seek(int64, int) (int64, syscall.Errno)

Seek implements File.Seek

func (DirFile) SetAppend 

func (DirFile) SetAppend(bool) syscall.Errno

SetAppend implements File.SetAppend

func (DirFile) SetNonblock 

func (DirFile) SetNonblock(bool) syscall.Errno

SetNonblock implements File.SetNonblock

func (DirFile) Truncate 

func (DirFile) Truncate(int64) syscall.Errno

Truncate implements File.Truncate

func (DirFile) Write 

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

Write implements File.Write

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 (*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 FS 

type FS interface {
	// String should return a human-readable format of the filesystem
	//
	// For example, if this filesystem is backed by the real directory
	// "/tmp/wasm", the expected value is "/tmp/wasm".
	//
	// When the host filesystem isn't a real filesystem, substitute a symbolic,
	// human-readable name. e.g. "virtual"
	String() string

	// OpenFile opens a file. It should be closed via Close on File.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EINVAL: `path` or `flag` is invalid.
	//   - syscall.EISDIR: the path was a directory, but flag included
	//     syscall.O_RDWR or syscall.O_WRONLY
	//   - syscall.ENOENT: `path` doesn't exist and `flag` doesn't contain
	//     os.O_CREATE.
	//
	// # 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 os.O_RDONLY fail
	// with a syscall.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 syscall.Errno is returned instead of os.PathError.
	//   - flag are the same as os.OpenFile, for example, os.O_CREATE.
	//   - Implications of permissions when os.O_CREATE 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 int, perm fs.FileMode) (File, syscall.Errno)

	// Lstat gets file status without following symbolic links.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.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) (Stat_t, syscall.Errno)

	// Stat gets file status.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.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) (Stat_t, syscall.Errno)

	// Mkdir makes a directory.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EINVAL: `path` is invalid.
	//   - syscall.EEXIST: `path` exists and is a directory.
	//   - syscall.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) syscall.Errno

	// Chmod changes the mode of the file.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EINVAL: `path` is invalid.
	//   - syscall.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) syscall.Errno

	// Chown changes the owner and group of a file.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EINVAL: `path` is invalid.
	//   - syscall.ENOENT: `path` does not exist.
	//
	// # Notes
	//
	//   - This is like syscall.Chown, except the `path` is relative to this
	//     file system.
	//   - This is like `chown` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/chown.html
	//   - This always returns syscall.ENOSYS on windows.
	Chown(path string, uid, gid int) syscall.Errno

	// Lchown changes the owner and group of a symbolic link.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EINVAL: `path` is invalid.
	//   - syscall.ENOENT: `path` does not exist.
	//
	// # Notes
	//
	//   - This is like syscall.Lchown, except the `path` is relative to this
	//     file system.
	//   - This is like `lchown` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/lchown.html
	//   - Windows will always return syscall.ENOSYS
	Lchown(path string, uid, gid int) syscall.Errno

	// Rename renames file or directory.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EINVAL: `from` or `to` is invalid.
	//   - syscall.ENOENT: `from` or `to` don't exist.
	//   - syscall.ENOTDIR: `from` is a directory and `to` exists as a file.
	//   - syscall.EISDIR: `from` is a file and `to` exists as a directory.
	//   - syscall.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) syscall.Errno

	// Rmdir removes a directory.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EINVAL: `path` is invalid.
	//   - syscall.ENOENT: `path` doesn't exist.
	//   - syscall.ENOTDIR: `path` exists, but isn't a directory.
	//   - syscall.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 syscall.ENOTDIR to syscall.ENOENT.
	Rmdir(path string) syscall.Errno

	// Unlink removes a directory entry.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EINVAL: `path` is invalid.
	//   - syscall.ENOENT: `path` doesn't exist.
	//   - syscall.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) syscall.Errno

	// Link creates a "hard" link from oldPath to newPath, in contrast to a
	// soft link (via Symlink).
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EPERM: `oldPath` is invalid.
	//   - syscall.ENOENT: `oldPath` doesn't exist.
	//   - syscall.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) syscall.Errno

	// Symlink creates a "soft" link from oldPath to newPath, in contrast to a
	// hard link (via Link).
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EPERM: `oldPath` or `newPath` is invalid.
	//   - syscall.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, syscall.EPERM results.
	//     See https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links
	Symlink(oldPath, linkName string) syscall.Errno

	// Readlink reads the contents of a symbolic link.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.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, syscall.Errno)

	// Truncate truncates a file to a specified length.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EINVAL: `path` is invalid or size is negative.
	//   - syscall.ENOENT: `path` doesn't exist.
	//   - syscall.EISDIR: `path` is a directory.
	//   - syscall.EACCES: `path` doesn't have write access.
	//
	// # Notes
	//
	//   - This is like syscall.Truncate, except the path is relative to this
	//     filesystem.
	//   - This is like `truncate` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/truncate.html
	Truncate(path string, size int64) syscall.Errno

	// Utimens set file access and modification times on a path relative to
	// this file system, at nanosecond precision.
	//
	// # Parameters
	//
	// The `times` parameter includes the access and modification timestamps to
	// assign. Special syscall.Timespec NSec values platform.UTIME_NOW and
	// platform.UTIME_OMIT may be specified instead of real timestamps. A nil
	// `times` parameter behaves the same as if both were set to
	// platform.UTIME_NOW.
	//
	// When the `symlinkFollow` parameter is true and the path is a symbolic link,
	// the target of expanding that link is updated.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EINVAL: `path` is invalid.
	//   - syscall.EEXIST: `path` exists and is a directory.
	//   - syscall.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, times *[2]syscall.Timespec, symlinkFollow bool) syscall.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 syscall.ENO

Errors

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

Restricting to syscall.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 

type File interface {
	// Ino returns the inode (Stat_t.Ino) of this file, zero if unknown or an
	// error there was an error retrieving it.
	//
	// # Errors
	//
	// Possible errors are those from Stat, except syscall.ENOSYS should not
	// be returned. Zero should be returned if there is no implementation.
	//
	// # Notes
	//
	//   - Some implementations implement this with a cached call to Stat.
	Ino() (uint64, syscall.Errno)

	// IsNonblock returns true if the file was opened with O_NONBLOCK, or
	// SetNonblock 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.
	IsNonblock() bool

	// SetNonblock toggles the non-blocking mode (O_NONBLOCK) of this file.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EBADF: the file or directory was closed.
	//
	// # Notes
	//
	//   - This is like syscall.SetNonblock and `fcntl` with O_NONBLOCK in
	//     POSIX. See https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html
	SetNonblock(enable bool) syscall.Errno

	// IsAppend returns true if the file was opened with syscall.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 (syscall.O_APPEND) of this file.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.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) syscall.Errno

	// Stat is similar to syscall.Fstat.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.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() (Stat_t, syscall.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.
	//
	// # Notes
	//
	//   - Some implementations implement this with a cached call to Stat.
	IsDir() (bool, syscall.Errno)

	// Read attempts to read all bytes in the file into `buf`, and returns the
	// count read even on error.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EBADF: the file or directory was closed or not readable.
	//   - syscall.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 syscall.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 syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EBADF: the file or directory was closed or not readable.
	//   - syscall.EINVAL: the offset was negative.
	//   - syscall.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 syscall.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 syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EBADF: the file or directory was closed or not readable.
	//   - syscall.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 syscall.Errno)

	// PollRead returns if the file has data ready to be read or an error.
	//
	// # Parameters
	//
	// The `timeout` parameter when nil blocks up to forever.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//
	// # Notes
	//
	//   - This is like `poll` in POSIX, for a single file.
	//     See https://pubs.opengroup.org/onlinepubs/9699919799/functions/poll.html
	//   - No-op files, such as those which read from /dev/null, should return
	//     immediately true to avoid hangs (because data will never become
	//     available).
	PollRead(timeout *time.Duration) (ready bool, 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. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.ENOTDIR: the file was not a directory
	//
	// # Notes
	//
	//   - This is like `Readdir` on os.File, but unlike `readdir` in POSIX.
	//     See https://pubs.opengroup.org/onlinepubs/9699919799/functions/readdir.html
	//   - For portability reasons, no error is returned at the end of the
	//     directory, 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
	Readdir(n int) (dirents []Dirent, errno syscall.Errno)

	// Write attempts to write all bytes in `p` to the file, and returns the
	// count written even on error.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.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 syscall.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 syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EBADF: the file or directory was closed or not writeable.
	//   - syscall.EINVAL: the offset was negative.
	//   - syscall.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 syscall.Errno)

	// Truncate truncates a file to a specified length.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EBADF: the file or directory was closed.
	//   - syscall.EINVAL: the `size` is negative.
	//   - syscall.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) syscall.Errno

	// Sync synchronizes changes to the file.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.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 syscall.ENOSYS when
	//     unimplemented. This prevents fake filesystems from erring.
	//   - Windows does not error when calling Sync on a closed file.
	Sync() syscall.Errno

	// Datasync synchronizes the data of a file.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.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 syscall.ENOSYS when
	//     unimplemented. This prevents fake filesystems from erring.
	//   - As this is commonly missing, some implementations dispatch to Sync.
	Datasync() syscall.Errno

	// Chmod changes the mode of the file.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EBADF: the file or directory was closed.
	//
	// # Notes
	//
	//   - This is like syscall.Fchmod and `fchmod` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/fchmod.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(fs.FileMode) syscall.Errno

	// Chown changes the owner and group of a file.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.EBADF: the file or directory was closed.
	//
	// # Notes
	//
	//   - This is like syscall.Fchown and `fchown` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/fchown.html
	//   - This always returns syscall.ENOSYS on windows.
	Chown(uid, gid int) syscall.Errno

	// Utimens set file access and modification times of this file, 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.
	//
	// # Errors
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//   - syscall.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 syscall.O_RDWR, which means you
	//     cannot use this to update timestamps on a directory (syscall.EPERM).
	Utimens(times *[2]syscall.Timespec) syscall.Errno

	// Close closes the underlying file.
	//
	// A zero syscall.Errno is success. The below are expected otherwise:
	//   - syscall.ENOSYS: the implementation does not support this function.
	//
	// # Notes
	//
	//   - This is like syscall.Close and `close` in POSIX. See
	//     https://pubs.opengroup.org/onlinepubs/9699919799/functions/close.html
	Close() syscall.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 syscall.ENOSYS.

Errors

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

Restricting to syscall.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 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.

type UnimplementedFS 

type UnimplementedFS struct{}

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

func (UnimplementedFS) Chmod 

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

Chmod implements FS.Chmod

func (UnimplementedFS) Chown 

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

Chown implements FS.Chown

func (UnimplementedFS) Lchown 

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

Lchown implements FS.Lchown 

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

Link implements FS.Link

func (UnimplementedFS) Lstat 

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

Lstat implements FS.Lstat

func (UnimplementedFS) Mkdir 

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

Mkdir implements FS.Mkdir

func (UnimplementedFS) Open 

func (UnimplementedFS) Open(name string) (fs.File, error)

Open implements the same method as documented on fs.FS

func (UnimplementedFS) OpenFile 

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

OpenFile implements FS.OpenFile 

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

Readlink implements FS.Readlink

func (UnimplementedFS) Rename 

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

Rename implements FS.Rename

func (UnimplementedFS) Rmdir 

func (UnimplementedFS) Rmdir(path string) syscall.Errno

Rmdir implements FS.Rmdir

func (UnimplementedFS) Stat 

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

Stat implements FS.Stat

func (UnimplementedFS) String 

func (UnimplementedFS) String() string

String implements fmt.Stringer 

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

Symlink implements FS.Symlink

func (UnimplementedFS) Truncate 

func (UnimplementedFS) Truncate(string, int64) syscall.Errno

Truncate implements FS.Truncate 

func (UnimplementedFS) Unlink(path string) syscall.Errno

Unlink implements FS.Unlink

func (UnimplementedFS) Utimens 

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

Utimens implements FS.Utimens

type UnimplementedFile 

type UnimplementedFile struct{}

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

This should be embedded to have forward compatible implementations.

func (UnimplementedFile) Chmod 

func (UnimplementedFile) Chmod(fs.FileMode) syscall.Errno

Chmod implements File.Chmod

func (UnimplementedFile) Chown 

func (UnimplementedFile) Chown(int, int) syscall.Errno

Chown implements File.Chown

func (UnimplementedFile) Close 

func (UnimplementedFile) Close() (errno syscall.Errno)

Close implements File.Close

func (UnimplementedFile) Datasync 

func (UnimplementedFile) Datasync() syscall.Errno

Datasync implements File.Datasync

func (UnimplementedFile) Ino 

func (UnimplementedFile) Ino() (uint64, syscall.Errno)

Ino implements File.Ino

func (UnimplementedFile) IsAppend 

func (UnimplementedFile) IsAppend() bool

IsAppend implements File.IsAppend

func (UnimplementedFile) IsDir 

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

IsDir implements File.IsDir

func (UnimplementedFile) IsNonblock 

func (UnimplementedFile) IsNonblock() bool

IsNonblock implements File.IsNonblock

func (UnimplementedFile) PollRead 

func (UnimplementedFile) PollRead(*time.Duration) (ready bool, errno syscall.Errno)

PollRead implements File.PollRead

func (UnimplementedFile) Pread 

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

Pread implements File.Pread

func (UnimplementedFile) Pwrite 

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

Pwrite implements File.Pwrite

func (UnimplementedFile) Read 

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

Read implements File.Read

func (UnimplementedFile) Readdir 

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

Readdir implements File.Readdir

func (UnimplementedFile) Seek 

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

Seek implements File.Seek

func (UnimplementedFile) SetAppend 

func (UnimplementedFile) SetAppend(bool) syscall.Errno

SetAppend implements File.SetAppend

func (UnimplementedFile) SetNonblock 

func (UnimplementedFile) SetNonblock(bool) syscall.Errno

SetNonblock implements File.SetNonblock

func (UnimplementedFile) Stat 

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

Stat implements File.Stat

func (UnimplementedFile) Sync 

func (UnimplementedFile) Sync() syscall.Errno

Sync implements File.Sync

func (UnimplementedFile) Truncate 

func (UnimplementedFile) Truncate(int64) syscall.Errno

Truncate implements File.Truncate

func (UnimplementedFile) Utimens 

func (UnimplementedFile) Utimens(*[2]syscall.Timespec) syscall.Errno

Utimens implements File.Utimens

func (UnimplementedFile) Write 

func (UnimplementedFile) Write([]byte) (int, syscall.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.