package fsapi

Import Path
	github.com/tetratelabs/wazero/internal/fsapi (on go.dev)

Dependency Relation
	imports one package, and imported by 2 packages

Involved Source Files

	    file.go
	    poll.go
	    unimplemented.go
Package-Level Type Names (total 2)

	/* sort by: alphabet | popularity */
	 type File (interface)
		File includes methods not yet ready to document for end users, notably
		non-blocking functionality.
		
		Particularly, Poll is subject to debate. For example, whether a user should
		be able to choose how to implement timeout or not. Currently, this interface
		allows the user to choose to sleep or use native polling, and which choice
		they make impacts thread behavior as summarized here:
		https://github.com/tetratelabs/wazero/pull/1606#issuecomment-1665475516

		Methods (total 20)
			( File) Close() sys.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

			( File) Datasync() sys.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.

			( File) Dev() (uint64, sys.Errno)
				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.

			( File) Ino() (sys.Inode, sys.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.

			( File) IsAppend() bool
				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.

			( File) IsDir() (bool, sys.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.

			( File) IsNonblock() bool
				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.

			( File) Poll(flag Pflag, timeoutMillis int32) (ready bool, errno experimentalsys.Errno)
				Poll returns if the file has data ready to be read or written.
				
				# Parameters
				
				The `flag` parameter determines which event to await, such as POLLIN,
				POLLOUT, or a combination like `POLLIN|POLLOUT`.
				
				The `timeoutMillis` parameter is how long to block for an event, or
				interrupted, in milliseconds. There are two special values:
				  - zero returns immediately
				  - any negative value blocks any amount of time
				
				# Results
				
				`ready` means there was data ready to read or written. False can mean no
				event was ready or `errno` is not zero.
				
				A zero `errno` is success. The below are expected otherwise:
				  - ENOSYS: the implementation does not support this function.
				  - ENOTSUP: the implementation does not the flag combination.
				  - EINTR: the call was interrupted prior to an event.
				
				# 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, as data will never become available.
				  - See /RATIONALE.md for detailed notes including impact of blocking.

			( File) Pread(buf []byte, off int64) (n int, errno sys.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.

			( File) Pwrite(buf []byte, off int64) (n int, errno sys.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

			( File) Read(buf []byte) (n int, errno sys.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.

			( File) Readdir(n int) (dirents []sys.Dirent, errno sys.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.

			( File) Seek(offset int64, whence int) (newOffset int64, errno sys.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

			( File) SetAppend(enable bool) sys.Errno
				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

			( File) SetNonblock(enable bool) experimentalsys.Errno
				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

			( File) Stat() (sys.Stat_t, sys.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.

			( File) Sync() sys.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.

			( File) Truncate(size int64) sys.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.

			( File) Utimens(atim, mtim int64) sys.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).

			( File) Write(buf []byte) (n int, errno sys.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

		Implemented By (at least one exported)
			*github.com/tetratelabs/wazero/internal/sys.StdinFile
		Implements (at least one exported)
			 File : github.com/tetratelabs/wazero/experimental/sys.File
		As Outputs Of (at least 2)
			func Adapt(f experimentalsys.File) File
			func github.com/tetratelabs/wazero/internal/sysfs.NewStdioFile(stdin bool, f fs.File) (File, error)

	 type Pflag uint32 (basic type)
		Pflag are bit flags used for File.Poll. Values, including zero, should not
		be interpreted numerically. Instead, use by constants prefixed with 'POLL'.
		
		# Notes
		
		  - This is like `pollfd.events` flags for `poll` in POSIX. See
		    https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/poll.h.html

		As Inputs Of (at least one exported)
			func File.Poll(flag Pflag, timeoutMillis int32) (ready bool, errno experimentalsys.Errno)
		As Types Of (total 2)
			const POLLIN
			const POLLOUT


Package-Level Functions (only one)

	 func Adapt(f experimentalsys.File) File
Package-Level Constants (total 2)

	const POLLIN Pflag = 1
		POLLIN is a read event.

	const POLLOUT Pflag = 2
		POLLOUT is a write event.

The pages are generated with Golds v0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.