System.FS.API.Types

When opening a file:

How to hOpen a new file.

Each mode of file operation has an associated AllowExisting parameter which specifies the semantics of how to handle the existence or non-existence of the file.

Notably however, opening a file in read mode with the ReadMode value implicitly has the associated AllowExisting value of MustExist. This is because opening a non-existing file in ReadMode provides access to exactly 0 bytes of data and is hence a useless operation.

A mode that determines the effect of GHC.Internal.System.IO.hSeek hdl mode i.

Mount point

FsPaths are not absolute paths, but must be interpreted with respect to a particualar mount point.

Create a path from a list of directory/file names. All of the names should be non-empty.

Drop the final component of the path

Undefined if the path is empty.

Split FsPath is essentially (init fp, last fp)

Like init and last, Nothing if empty.

Constructor for FsPath ensures path is in normal form

Add an extension, even if there is already one there.

This works similarly to Filepath.<.>.

An alias for <.>.

Combine two paths with a path separator.

This works similarly to </>, but since the arguments are relative paths, the corner cases for </> do not apply. Specifically, the second path will never start with a path separator or a drive letter, so the result is simply the concatenation of the two paths.

If either operand is empty, the other operand is returned. The result of combining two empty paths is the empty path

An alias for </>.

For better error reporting to the end user, we want to include the mount point of the file. But the mountpoint may not always be available, like when we mock the fs or we simulate fs errors.

Like fsToFsErrorPath, but when we don't have a MountPoint

Check if two errors are semantically the same error

This ignores the error string, the errno, and the callstack.

Translate exceptions thrown by IO functions to FsError

We take the FsPath as an argument. We could try to translate back from a FilePath to an FsPath (given a MountPoint), but we know the FsPath at all times anyway and not all IO exceptions actually include a filepath.

Assign an FsErrorType to the given IOError.

Note that we don't always use the classification made by errnoToIOError (also see System.IO.Error) because it combines some errors into one IOErrorType, e.g., EMFILE (too many open files) and ENOSPC (no space left on device) both result in ResourceExhausted while we want to keep them separate. For this reason, we do a classification of our own based on the errno while sometimes deferring to the existing classification.

See the ERRNO(3) man page for the meaning of the different errnos.