package fsapi
import "github.com/tetratelabs/wazero/internal/fsapi"
Index ¶
- type DirFile
- func (DirFile) IsAppend() bool
- func (DirFile) IsDir() (bool, experimentalsys.Errno)
- func (DirFile) IsNonblock() bool
- func (DirFile) PollRead(*time.Duration) (ready bool, errno experimentalsys.Errno)
- func (DirFile) Pread([]byte, int64) (int, experimentalsys.Errno)
- func (DirFile) Pwrite([]byte, int64) (int, experimentalsys.Errno)
- func (DirFile) Read([]byte) (int, experimentalsys.Errno)
- func (DirFile) SetAppend(bool) experimentalsys.Errno
- func (DirFile) SetNonblock(bool) experimentalsys.Errno
- func (DirFile) Truncate(int64) experimentalsys.Errno
- func (DirFile) Write([]byte) (int, experimentalsys.Errno)
- type Dirent
- type FS
- type File
- type FileType
- type Oflag
- type UnimplementedFS
- func (UnimplementedFS) Chmod(path string, perm fs.FileMode) experimentalsys.Errno
- func (UnimplementedFS) Link(_, _ string) experimentalsys.Errno
- func (UnimplementedFS) Lstat(path string) (sys.Stat_t, experimentalsys.Errno)
- func (UnimplementedFS) Mkdir(path string, perm fs.FileMode) experimentalsys.Errno
- func (UnimplementedFS) Open(name string) (fs.File, error)
- func (UnimplementedFS) OpenFile(path string, flag Oflag, perm fs.FileMode) (File, experimentalsys.Errno)
- func (UnimplementedFS) Readlink(path string) (string, experimentalsys.Errno)
- func (UnimplementedFS) Rename(from, to string) experimentalsys.Errno
- func (UnimplementedFS) Rmdir(path string) experimentalsys.Errno
- func (UnimplementedFS) Stat(path string) (sys.Stat_t, experimentalsys.Errno)
- func (UnimplementedFS) String() string
- func (UnimplementedFS) Symlink(_, _ string) experimentalsys.Errno
- func (UnimplementedFS) Truncate(string, int64) experimentalsys.Errno
- func (UnimplementedFS) Unlink(path string) experimentalsys.Errno
- func (UnimplementedFS) Utimens(path string, times *[2]syscall.Timespec) experimentalsys.Errno
- type UnimplementedFile
- func (UnimplementedFile) Close() (errno experimentalsys.Errno)
- func (UnimplementedFile) Datasync() experimentalsys.Errno
- func (UnimplementedFile) Dev() (uint64, experimentalsys.Errno)
- func (UnimplementedFile) Ino() (sys.Inode, experimentalsys.Errno)
- func (UnimplementedFile) IsAppend() bool
- func (UnimplementedFile) IsDir() (bool, experimentalsys.Errno)
- func (UnimplementedFile) IsNonblock() bool
- func (UnimplementedFile) PollRead(*time.Duration) (ready bool, errno experimentalsys.Errno)
- func (UnimplementedFile) Pread([]byte, int64) (int, experimentalsys.Errno)
- func (UnimplementedFile) Pwrite([]byte, int64) (int, experimentalsys.Errno)
- func (UnimplementedFile) Read([]byte) (int, experimentalsys.Errno)
- func (UnimplementedFile) Readdir(int) (dirents []Dirent, errno experimentalsys.Errno)
- func (UnimplementedFile) Seek(int64, int) (int64, experimentalsys.Errno)
- func (UnimplementedFile) SetAppend(bool) experimentalsys.Errno
- func (UnimplementedFile) SetNonblock(bool) experimentalsys.Errno
- func (UnimplementedFile) Stat() (sys.Stat_t, experimentalsys.Errno)
- func (UnimplementedFile) Sync() experimentalsys.Errno
- func (UnimplementedFile) Truncate(int64) experimentalsys.Errno
- func (UnimplementedFile) Utimens(*[2]syscall.Timespec) experimentalsys.Errno
- func (UnimplementedFile) Write([]byte) (int, experimentalsys.Errno)
Types ¶
type DirFile ¶
type DirFile struct{}
DirFile is embeddable to reduce the amount of functions to implement a file.
func (DirFile) IsAppend ¶
IsAppend implements File.IsAppend
func (DirFile) IsDir ¶
func (DirFile) IsDir() (bool, experimentalsys.Errno)
IsDir implements File.IsDir
func (DirFile) IsNonblock ¶
IsNonblock implements File.IsNonblock
func (DirFile) PollRead ¶
PollRead implements File.PollRead
func (DirFile) Pread ¶
Pread implements File.Pread
func (DirFile) Pwrite ¶
Pwrite implements File.Pwrite
func (DirFile) Read ¶
func (DirFile) Read([]byte) (int, experimentalsys.Errno)
Read implements File.Read
func (DirFile) SetAppend ¶
func (DirFile) SetAppend(bool) experimentalsys.Errno
SetAppend implements File.SetAppend
func (DirFile) SetNonblock ¶
func (DirFile) SetNonblock(bool) experimentalsys.Errno
SetNonblock implements File.SetNonblock
func (DirFile) Truncate ¶
func (DirFile) Truncate(int64) experimentalsys.Errno
Truncate implements File.Truncate
func (DirFile) Write ¶
func (DirFile) Write([]byte) (int, experimentalsys.Errno)
Write implements File.Write
type Dirent ¶
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
- This extends `dirent` defined in POSIX with some fields defined by Linux. See https://man7.org/linux/man-pages/man3/readdir.3.html and https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/dirent.h.html
- This has a subset of fields defined in Stat_t. Notably, there is no field corresponding to Stat_t.Dev because that value will be constant for all files in a directory. To get the Dev value, call File.Stat on the directory File.Readdir was called on.
func (*Dirent) IsDir ¶
IsDir returns true if the Type is fs.ModeDir.
func (*Dirent) String ¶
type FS ¶
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: // - sys.ENOSYS: the implementation does not support this function. // - sys.EINVAL: `path` or `flag` is invalid. // - sys.EISDIR: the path was a directory, but flag included O_RDWR or // O_WRONLY // - sys.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, experimentalsys.Errno) // Lstat gets file status without following symbolic links. // // # Errors // // A zero Errno is success. The below are expected otherwise: // - sys.ENOSYS: the implementation does not support this function. // - sys.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, experimentalsys.Errno) // Stat gets file status. // // # Errors // // A zero Errno is success. The below are expected otherwise: // - sys.ENOSYS: the implementation does not support this function. // - sys.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, experimentalsys.Errno) // Mkdir makes a directory. // // # Errors // // A zero Errno is success. The below are expected otherwise: // - sys.ENOSYS: the implementation does not support this function. // - sys.EINVAL: `path` is invalid. // - sys.EEXIST: `path` exists and is a directory. // - sys.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) experimentalsys.Errno // Chmod changes the mode of the file. // // # Errors // // A zero Errno is success. The below are expected otherwise: // - sys.ENOSYS: the implementation does not support this function. // - sys.EINVAL: `path` is invalid. // - sys.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) experimentalsys.Errno // Rename renames file or directory. // // # Errors // // A zero Errno is success. The below are expected otherwise: // - sys.ENOSYS: the implementation does not support this function. // - sys.EINVAL: `from` or `to` is invalid. // - sys.ENOENT: `from` or `to` don't exist. // - sys.ENOTDIR: `from` is a directory and `to` exists as a file. // - sys.EISDIR: `from` is a file and `to` exists as a directory. // - sys.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) experimentalsys.Errno // Rmdir removes a directory. // // # Errors // // A zero Errno is success. The below are expected otherwise: // - sys.ENOSYS: the implementation does not support this function. // - sys.EINVAL: `path` is invalid. // - sys.ENOENT: `path` doesn't exist. // - sys.ENOTDIR: `path` exists, but isn't a directory. // - sys.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 sys.ENOTDIR to sys.ENOENT. Rmdir(path string) experimentalsys.Errno // Unlink removes a directory entry. // // # Errors // // A zero Errno is success. The below are expected otherwise: // - sys.ENOSYS: the implementation does not support this function. // - sys.EINVAL: `path` is invalid. // - sys.ENOENT: `path` doesn't exist. // - sys.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) experimentalsys.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: // - sys.ENOSYS: the implementation does not support this function. // - sys.EPERM: `oldPath` is invalid. // - sys.ENOENT: `oldPath` doesn't exist. // - sys.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) experimentalsys.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: // - sys.ENOSYS: the implementation does not support this function. // - sys.EPERM: `oldPath` or `newPath` is invalid. // - sys.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, sys.EPERM results. // See https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links Symlink(oldPath, linkName string) experimentalsys.Errno // Readlink reads the contents of a symbolic link. // // # Errors // // A zero Errno is success. The below are expected otherwise: // - sys.ENOSYS: the implementation does not support this function. // - sys.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, experimentalsys.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 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. If the path is a // symbolic link, the target of expanding that link is updated. // // # Errors // // A zero Errno is success. The below are expected otherwise: // - sys.ENOSYS: the implementation does not support this function. // - sys.EINVAL: `path` is invalid. // - sys.EEXIST: `path` exists and is a directory. // - sys.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) experimentalsys.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 ¶
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, experimentalsys.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, experimentalsys.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, experimentalsys.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 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.SetNonblock and `fcntl` with O_NONBLOCK in // POSIX. See https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html SetNonblock(enable bool) experimentalsys.Errno // IsAppend returns true if the file was opened with fsapi.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 (fsapi.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) experimentalsys.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, experimentalsys.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 experimentalsys.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 experimentalsys.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 experimentalsys.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 Errno is success. The below are expected otherwise: // - 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 experimentalsys.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 experimentalsys.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 experimentalsys.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 experimentalsys.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) experimentalsys.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() experimentalsys.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() experimentalsys.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 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 fsapi.O_RDWR, which means you // cannot use this to update timestamps on a directory (EPERM). Utimens(times *[2]syscall.Timespec) experimentalsys.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() experimentalsys.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 ¶
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 ¶
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
- O_RDONLY, O_RDWR and O_WRONLY are mutually exclusive, while the other flags can coexist bitwise.
- This is like `flag` in os.OpenFile and `oflag` in POSIX. See https://pubs.opengroup.org/onlinepubs/9699919799/functions/open.html
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 ¶
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 ¶
func (UnimplementedFS) Chmod(path string, perm fs.FileMode) experimentalsys.Errno
Chmod implements FS.Chmod
func (UnimplementedFS) Link ¶
func (UnimplementedFS) Link(_, _ string) experimentalsys.Errno
Link implements FS.Link
func (UnimplementedFS) Lstat ¶
func (UnimplementedFS) Lstat(path string) (sys.Stat_t, experimentalsys.Errno)
Lstat implements FS.Lstat
func (UnimplementedFS) Mkdir ¶
func (UnimplementedFS) Mkdir(path string, perm fs.FileMode) experimentalsys.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 Oflag, perm fs.FileMode) (File, experimentalsys.Errno)
OpenFile implements FS.OpenFile
func (UnimplementedFS) Readlink ¶
func (UnimplementedFS) Readlink(path string) (string, experimentalsys.Errno)
Readlink implements FS.Readlink
func (UnimplementedFS) Rename ¶
func (UnimplementedFS) Rename(from, to string) experimentalsys.Errno
Rename implements FS.Rename
func (UnimplementedFS) Rmdir ¶
func (UnimplementedFS) Rmdir(path string) experimentalsys.Errno
Rmdir implements FS.Rmdir
func (UnimplementedFS) Stat ¶
func (UnimplementedFS) Stat(path string) (sys.Stat_t, experimentalsys.Errno)
Stat implements FS.Stat
func (UnimplementedFS) String ¶
func (UnimplementedFS) String() string
String implements fmt.Stringer
func (UnimplementedFS) Symlink ¶
func (UnimplementedFS) Symlink(_, _ string) experimentalsys.Errno
Symlink implements FS.Symlink
func (UnimplementedFS) Truncate ¶
func (UnimplementedFS) Truncate(string, int64) experimentalsys.Errno
Truncate implements FS.Truncate
func (UnimplementedFS) Unlink ¶
func (UnimplementedFS) Unlink(path string) experimentalsys.Errno
Unlink implements FS.Unlink
func (UnimplementedFS) Utimens ¶
func (UnimplementedFS) Utimens(path string, times *[2]syscall.Timespec) experimentalsys.Errno
Utimens implements FS.Utimens
type UnimplementedFile ¶
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 ¶
func (UnimplementedFile) Close() (errno experimentalsys.Errno)
Close implements File.Close
func (UnimplementedFile) Datasync ¶
func (UnimplementedFile) Datasync() experimentalsys.Errno
Datasync implements File.Datasync
func (UnimplementedFile) Dev ¶
func (UnimplementedFile) Dev() (uint64, experimentalsys.Errno)
Dev implements File.Dev
func (UnimplementedFile) Ino ¶
func (UnimplementedFile) Ino() (sys.Inode, experimentalsys.Errno)
Ino implements File.Ino
func (UnimplementedFile) IsAppend ¶
func (UnimplementedFile) IsAppend() bool
IsAppend implements File.IsAppend
func (UnimplementedFile) IsDir ¶
func (UnimplementedFile) IsDir() (bool, experimentalsys.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 experimentalsys.Errno)
PollRead implements File.PollRead
func (UnimplementedFile) Pread ¶
func (UnimplementedFile) Pread([]byte, int64) (int, experimentalsys.Errno)
Pread implements File.Pread
func (UnimplementedFile) Pwrite ¶
func (UnimplementedFile) Pwrite([]byte, int64) (int, experimentalsys.Errno)
Pwrite implements File.Pwrite
func (UnimplementedFile) Read ¶
func (UnimplementedFile) Read([]byte) (int, experimentalsys.Errno)
Read implements File.Read
func (UnimplementedFile) Readdir ¶
func (UnimplementedFile) Readdir(int) (dirents []Dirent, errno experimentalsys.Errno)
Readdir implements File.Readdir
func (UnimplementedFile) Seek ¶
func (UnimplementedFile) Seek(int64, int) (int64, experimentalsys.Errno)
Seek implements File.Seek
func (UnimplementedFile) SetAppend ¶
func (UnimplementedFile) SetAppend(bool) experimentalsys.Errno
SetAppend implements File.SetAppend
func (UnimplementedFile) SetNonblock ¶
func (UnimplementedFile) SetNonblock(bool) experimentalsys.Errno
SetNonblock implements File.SetNonblock
func (UnimplementedFile) Stat ¶
func (UnimplementedFile) Stat() (sys.Stat_t, experimentalsys.Errno)
Stat implements File.Stat
func (UnimplementedFile) Sync ¶
func (UnimplementedFile) Sync() experimentalsys.Errno
Sync implements File.Sync
func (UnimplementedFile) Truncate ¶
func (UnimplementedFile) Truncate(int64) experimentalsys.Errno
Truncate implements File.Truncate
func (UnimplementedFile) Utimens ¶
func (UnimplementedFile) Utimens(*[2]syscall.Timespec) experimentalsys.Errno
Utimens implements File.Utimens
func (UnimplementedFile) Write ¶
func (UnimplementedFile) Write([]byte) (int, experimentalsys.Errno)
Write implements File.Write
Source Files ¶
dir.go file.go fs.go oflag.go unimplemented.go
- Version
- v1.3.1
- Published
- Jul 22, 2023
- Platform
- darwin/amd64
- Imports
- 6 packages
- Last checked
- 8 hours ago –
Tools for package owners.