package fs

Import Path
	github.com/polarsignals/wal/fs (on go.dev)

Dependency Relation
	imports 8 packages, and imported by one package

Involved Source Files

	    file.go
	    fs.go
	    fs_nowasm.go
Package-Level Type Names (total 2)

	/* sort by: alphabet | popularity */
	 type File (struct)
		File wraps an os.File and implements types.WritableFile. It ensures that the
		first time Sync is called on the file, that the parent directory is also
		Fsynced to ensure a crash won't cause the FS to forget the file is there.
		
		Postponing this allows us to ensure that we do the minimum necessary fsyncs
		but still ensure all required fsyncs are done by the time we acknowledge
		committed data in the new file.

		Fields (only one)
			File os.File
		Methods (total 24)
			(*File) Chdir() error
				Chdir changes the current working directory to the file,
				which must be a directory.
				If there is an error, it will be of type [*PathError].

			(*File) Chmod(mode os.FileMode) error
				Chmod changes the mode of the file to mode.
				If there is an error, it will be of type [*PathError].

			(*File) Chown(uid, gid int) error
				Chown changes the numeric uid and gid of the named file.
				If there is an error, it will be of type [*PathError].
				
				On Windows, it always returns the [syscall.EWINDOWS] error, wrapped
				in [*PathError].

			(*File) Close() error
				Close closes the [File], rendering it unusable for I/O.
				On files that support [File.SetDeadline], any pending I/O operations will
				be canceled and return immediately with an [ErrClosed] error.
				Close will return an error if it has already been called.

			(*File) Fd() uintptr
				Fd returns the system file descriptor or handle referencing the open file.
				If f is closed, the descriptor becomes invalid.
				If f is garbage collected, a finalizer may close the descriptor,
				making it invalid; see [runtime.SetFinalizer] for more information on when
				a finalizer might be run.
				
				Do not close the returned descriptor; that could cause a later
				close of f to close an unrelated descriptor.
				
				Fd's behavior differs on some platforms:
				
				  - On Unix and Windows, [File.SetDeadline] methods will stop working.
				  - On Windows, the file descriptor will be disassociated from the
				    Go runtime I/O completion port if there are no concurrent I/O
				    operations on the file.
				
				For most uses prefer the f.SyscallConn method.

			(*File) Name() string
				Name returns the name of the file as presented to Open.
				
				It is safe to call Name after [Close].

			(*File) Read(b []byte) (n int, err error)
				Read reads up to len(b) bytes from the File and stores them in b.
				It returns the number of bytes read and any error encountered.
				At end of file, Read returns 0, io.EOF.

			(*File) ReadAt(b []byte, off int64) (n int, err error)
				ReadAt reads len(b) bytes from the File starting at byte offset off.
				It returns the number of bytes read and the error, if any.
				ReadAt always returns a non-nil error when n < len(b).
				At end of file, that error is io.EOF.

			(*File) ReadDir(n int) ([]os.DirEntry, error)
				ReadDir reads the contents of the directory associated with the file f
				and returns a slice of [DirEntry] values in directory order.
				Subsequent calls on the same file will yield later DirEntry records in the directory.
				
				If n > 0, ReadDir returns at most n DirEntry records.
				In this case, if ReadDir returns an empty slice, it will return an error explaining why.
				At the end of a directory, the error is [io.EOF].
				
				If n <= 0, ReadDir returns all the DirEntry records remaining in the directory.
				When it succeeds, it returns a nil error (not io.EOF).

			(*File) ReadFrom(r io.Reader) (n int64, err error)
				ReadFrom implements io.ReaderFrom.

			(*File) Readdir(n int) ([]os.FileInfo, error)
				Readdir reads the contents of the directory associated with file and
				returns a slice of up to n [FileInfo] values, as would be returned
				by [Lstat], in directory order. Subsequent calls on the same file will yield
				further FileInfos.
				
				If n > 0, Readdir returns at most n FileInfo structures. In this case, if
				Readdir returns an empty slice, it will return a non-nil error
				explaining why. At the end of a directory, the error is [io.EOF].
				
				If n <= 0, Readdir returns all the FileInfo from the directory in
				a single slice. In this case, if Readdir succeeds (reads all
				the way to the end of the directory), it returns the slice and a
				nil error. If it encounters an error before the end of the
				directory, Readdir returns the FileInfo read until that point
				and a non-nil error.
				
				Most clients are better served by the more efficient ReadDir method.

			(*File) Readdirnames(n int) (names []string, err error)
				Readdirnames reads the contents of the directory associated with file
				and returns a slice of up to n names of files in the directory,
				in directory order. Subsequent calls on the same file will yield
				further names.
				
				If n > 0, Readdirnames returns at most n names. In this case, if
				Readdirnames returns an empty slice, it will return a non-nil error
				explaining why. At the end of a directory, the error is [io.EOF].
				
				If n <= 0, Readdirnames returns all the names from the directory in
				a single slice. In this case, if Readdirnames succeeds (reads all
				the way to the end of the directory), it returns the slice and a
				nil error. If it encounters an error before the end of the
				directory, Readdirnames returns the names read until that point and
				a non-nil error.

			(*File) Seek(offset int64, whence int) (ret int64, err error)
				Seek sets the offset for the next Read or Write on file to offset, interpreted
				according to whence: 0 means relative to the origin of the file, 1 means
				relative to the current offset, and 2 means relative to the end.
				It returns the new offset and an error, if any.
				The behavior of Seek on a file opened with [O_APPEND] is not specified.

			(*File) SetDeadline(t time.Time) error
				SetDeadline sets the read and write deadlines for a File.
				It is equivalent to calling both SetReadDeadline and SetWriteDeadline.
				
				Only some kinds of files support setting a deadline. Calls to SetDeadline
				for files that do not support deadlines will return ErrNoDeadline.
				On most systems ordinary files do not support deadlines, but pipes do.
				
				A deadline is an absolute time after which I/O operations fail with an
				error instead of blocking. The deadline applies to all future and pending
				I/O, not just the immediately following call to Read or Write.
				After a deadline has been exceeded, the connection can be refreshed
				by setting a deadline in the future.
				
				If the deadline is exceeded a call to Read or Write or to other I/O
				methods will return an error that wraps ErrDeadlineExceeded.
				This can be tested using errors.Is(err, os.ErrDeadlineExceeded).
				That error implements the Timeout method, and calling the Timeout
				method will return true, but there are other possible errors for which
				the Timeout will return true even if the deadline has not been exceeded.
				
				An idle timeout can be implemented by repeatedly extending
				the deadline after successful Read or Write calls.
				
				A zero value for t means I/O operations will not time out.

			(*File) SetReadDeadline(t time.Time) error
				SetReadDeadline sets the deadline for future Read calls and any
				currently-blocked Read call.
				A zero value for t means Read will not time out.
				Not all files support setting deadlines; see SetDeadline.

			(*File) SetWriteDeadline(t time.Time) error
				SetWriteDeadline sets the deadline for any future Write calls and any
				currently-blocked Write call.
				Even if Write times out, it may return n > 0, indicating that
				some of the data was successfully written.
				A zero value for t means Write will not time out.
				Not all files support setting deadlines; see SetDeadline.

			(*File) Stat() (os.FileInfo, error)
				Stat returns the [FileInfo] structure describing file.
				If there is an error, it will be of type [*PathError].

			(*File) Sync() error
				Sync calls fsync on the underlying file. If this is the first call to Sync
				since creation it also fsyncs the parent dir.

			(*File) SyscallConn() (syscall.RawConn, error)
				SyscallConn returns a raw file.
				This implements the syscall.Conn interface.

			(*File) Truncate(size int64) error
				Truncate changes the size of the file.
				It does not change the I/O offset.
				If there is an error, it will be of type [*PathError].

			(*File) Write(b []byte) (n int, err error)
				Write writes len(b) bytes from b to the File.
				It returns the number of bytes written and an error, if any.
				Write returns a non-nil error when n != len(b).

			(*File) WriteAt(b []byte, off int64) (n int, err error)
				WriteAt writes len(b) bytes to the File starting at byte offset off.
				It returns the number of bytes written and an error, if any.
				WriteAt returns a non-nil error when n != len(b).
				
				If file was opened with the [O_APPEND] flag, WriteAt returns an error.

			(*File) WriteString(s string) (n int, err error)
				WriteString is like Write, but writes the contents of string s rather than
				a slice of bytes.

			(*File) WriteTo(w io.Writer) (n int64, err error)
				WriteTo implements io.WriterTo.

		Implements (at least 39)
			*File : github.com/polarsignals/wal/types.ReadableFile
			*File : github.com/polarsignals/wal/types.WritableFile
			*File : github.com/polarsignals/frostdb.Sync
			*File : github.com/polarsignals/frostdb/query/logicalplan.Named
			*File : github.com/apache/arrow-go/v18/arrow/ipc.ReadAtSeeker
			*File : github.com/apache/arrow-go/v18/internal/utils.Reader
			*File : github.com/apache/arrow-go/v18/parquet.ReaderAtSeeker
			*File : github.com/gobwas/ws.HandshakeHeader
			*File : github.com/miekg/dns.Writer
			*File : github.com/pion/datachannel.ReadDeadliner
			*File : github.com/pion/datachannel.WriteDeadliner
			*File : github.com/pion/stun.Connection
			*File : github.com/pion/stun/v3.Connection
			*File : github.com/prometheus/common/expfmt.Closer
			*File : go.uber.org/zap.Sink
			*File : go.uber.org/zap/zapcore.WriteSyncer
			*File : internal/bisect.Writer
			*File : io.Closer
			*File : io.ReadCloser
			*File : io.Reader
			*File : io.ReaderAt
			*File : io.ReaderFrom
			*File : io.ReadSeekCloser
			*File : io.ReadSeeker
			*File : io.ReadWriteCloser
			*File : io.ReadWriter
			*File : io.ReadWriteSeeker
			*File : io.Seeker
			*File : io.StringWriter
			*File : io.WriteCloser
			*File : io.Writer
			*File : io.WriterAt
			*File : io.WriterTo
			*File : io.WriteSeeker
			*File : io/fs.File
			*File : io/fs.ReadDirFile
			*File : mime/multipart.File
			*File : net/http.File
			*File : syscall.Conn

	 type FS (struct)
		FS implements the wal.VFS interface using GO's built in OS Filesystem (and a
		few helpers).
		
		TODO if we changed the interface to be Dir centric we could cache the open
		dir handle and save some time opening it on each Create in order to fsync.

		Methods (total 5)
			(*FS) Create(dir string, name string, size uint64) (types.WritableFile, error)
				Create creates a new file with the given name. If a file with the same name
				already exists an error is returned. If a non-zero size is given,
				implementations should make a best effort to pre-allocate the file to be
				that size. The dir must already exist and be writable to the current
				process.

			(*FS) Delete(dir string, name string) error
				Delete indicates the file is no longer required. Typically it should be
				deleted from the underlying system to free disk space.

			(*FS) ListDir(dir string) ([]string, error)
				ListDir returns a list of all files in the specified dir in lexicographical
				order. If the dir doesn't exist, it must return an error. Empty array with
				nil error is assumed to mean that the directory exists and was readable,
				but contains no files.

			(*FS) OpenReader(dir string, name string) (types.ReadableFile, error)
				OpenReader opens an existing file in read-only mode. If the file doesn't
				exist or permission is denied, an error is returned, otherwise no checks
				are made about the well-formedness of the file, it may be empty, the wrong
				size or corrupt in arbitrary ways.

			(*FS) OpenWriter(dir string, name string) (types.WritableFile, error)
				OpenWriter opens a file in read-write mode. If the file doesn't exist or
				permission is denied, an error is returned, otherwise no checks are made
				about the well-formedness of the file, it may be empty, the wrong size or
				corrupt in arbitrary ways.

		Implements (at least one exported)
			*FS : github.com/polarsignals/wal/types.VFS
		As Outputs Of (at least one exported)
			func New() *FS


Package-Level Functions (only one)

	 func New() *FS

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.