File

Utilities for accessing the filesystem & working with files.

Many of the functions in this module are not intended to be used directly, but rather for other libraries to be built on top of them.

1

from "wasi/file" include File

Types

Type declarations included in the File module.

File.FileDescriptor

1
2
3

enum FileDescriptor {
  FileDescriptor(Number),
}

Represents a handle to an open file on the system.

File.LookupFlag

1
2
3

enum LookupFlag {
  SymlinkFollow,
}

Flags that determine how paths should be resolved when looking up a file or directory.

Variants:

1

SymlinkFollow

Follow symlinks

File.OpenFlag

1
2
3
4
5
6

enum OpenFlag {
  Create,
  Directory,
  Exclusive,
  Truncate,
}

Flags that determine how a file or directory should be opened.

Variants:

1

Create

Create file if it does not exist.

1

Directory

Fail if not a directory.

1

Exclusive

Fail if file already exists.

1

Truncate

Truncate file to size 0.

File.Rights

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

enum Rights {
  FdDatasync,
  FdRead,
  FdSeek,
  FdSetFlags,
  FdSync,
  FdTell,
  FdWrite,
  FdAdvise,
  FdAllocate,
  PathCreateDirectory,
  PathCreateFile,
  PathLinkSource,
  PathLinkTarget,
  PathOpen,
  FdReaddir,
  PathReadlink,
  PathRenameSource,
  PathRenameTarget,
  PathFilestats,
  PathSetSize,
  PathSetTimes,
  FdFilestats,
  FdSetSize,
  FdSetTimes,
  PathSymlink,
  PathRemoveDirectory,
  PathUnlinkFile,
  PollFdReadwrite,
  SockShutdown,
}

Flags that determine which rights a FileDescriptor should have and which rights new FileDescriptors should inherit from it.

Variants:

1

FdDatasync

The right to invoke fdDatasync. If PathOpen is set, includes the right to invoke pathOpen with FdFlag::Dsync.

1

FdRead

The right to invoke fdRead. If Rights::FdSeek is set, includes the right to invoke fdPread.

1

FdSeek

The right to invoke fdSeek. This flag implies Rights::FdTell.

1

FdSetFlags

The right to invoke fdSetFlags.

1

FdSync

The right to invoke fdSync. If PathOpen is set, includes the right to invoke pathOpen with FdFlag::Rsync and FdFlag::Dsync.

1

FdTell

The right to invoke fdSeek in such a way that the file offset remains unaltered (i.e., Whence::Current with offset zero), or to invoke fdTell.

1

FdWrite

The right to invoke fdWrite. If Rights::FdSeek is set, includes the right to invoke fdPwrite.

1

FdAdvise

The right to invoke fdAdvise.

1

FdAllocate

The right to invoke fdAllocate.

1

PathCreateDirectory

The right to invoke pathCreateDirectory.

1

PathCreateFile

If PathOpen is set, the right to invoke pathOpen with OpenFlag::Create.

1

PathLinkSource

The right to invoke pathLink with the file descriptor as the source directory.

1

PathLinkTarget

The right to invoke pathLink with the file descriptor as the target directory.

1

PathOpen

The right to invoke pathOpen.

1

FdReaddir

The right to invoke fdReaddir.

1

PathReadlink

The right to invoke pathReadlink.

1

PathRenameSource

The right to invoke pathRename with the file descriptor as the source directory.

1

PathRenameTarget

The right to invoke pathRename with the file descriptor as the target directory.

1

PathFilestats

The right to invoke pathFilestats.

1

PathSetSize

The right to change a file’s size (there’s no pathSetSize). If PathOpen is set, includes the right to invoke pathOpen with OpenFlag::Truncate.

1

PathSetTimes

The right to invoke pathSetAccessTime, pathSetAccessTimeNow, pathSetModifiedTime, or pathSetModifiedTimeNow.

1

FdFilestats

The right to invoke fdFilestats.

1

FdSetSize

The right to invoke fdSetSize.

1

FdSetTimes

The right to invoke fdSetAccessTime, fdSetAccessTimeNow, fdSetModifiedTime, or fdSetModifiedTimeNow.

1

PathSymlink

The right to invoke pathSymlink.

1

PathRemoveDirectory

The right to invoke pathRemoveDirectory.

1

PathUnlinkFile

The right to invoke pathUnlinkFile.

1

PollFdReadwrite

If Rights::FdRead is set, includes the right to invoke pollOneoff (not yet implemented) to subscribe to EventType::FdRead. If Rights::FdWrite is set, includes the right to invoke pollOneoff (not yet implemented) to subscribe to EventType::FdWrite.

1

SockShutdown

The right to invoke sockShutdown (not yet implemented).

File.FdFlag

1
2
3
4
5
6
7

enum FdFlag {
  Append,
  Dsync,
  Nonblock,
  Rsync,
  Sync,
}

Flags that determine the mode(s) that a FileDescriptor operates in.

Variants:

1

Append

Append mode: Data written to the file is always appended to the file’s end.

1

Dsync

Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized.

1

Nonblock

Non-blocking mode.

1

Rsync

Synchronized read I/O operations.

File.Filetype

1
2
3
4
5
6
7
8
9
10

enum Filetype {
  Unknown,
  BlockDevice,
  CharacterDevice,
  Directory,
  RegularFile,
  SocketDatagram,
  SocketStream,
  SymbolicLink,
}

The type of file a FileDescriptor refers to.

Variants:

1

Unknown

The type of the file descriptor or file is unknown or is different from any of the other types specified.

1

BlockDevice

The file descriptor or file refers to a block device inode.

1

CharacterDevice

The file descriptor or file refers to a character device inode.

1

Directory

The file descriptor or file refers to a directory inode.

1

RegularFile

The file descriptor or file refers to a regular file inode.

1

SocketDatagram

The file descriptor or file refers to a datagram socket.

1

SocketStream

The file descriptor or file refers to a byte-stream socket.

1

SymbolicLink

The file refers to a symbolic link inode.

File.Whence

1
2
3
4
5

enum Whence {
  Set,
  Current,
  End,
}

Flags that determine where seeking should begin in a file.

Variants:

1

Set

Seek relative to start-of-file.

1

Current

Seek relative to current position.

1

End

Seek relative to end-of-file.

File.Stats

1
2
3
4
5
6

record Stats {
  filetype: Filetype,
  flags: List<FdFlag>,
  rights: List<Rights>,
  rightsInheriting: List<Rights>,
}

Information about a FileDescriptor.

File.Filestats

1
2
3
4
5
6
7
8
9
10

record Filestats {
  device: Int64,
  inode: Int64,
  filetype: Filetype,
  linkcount: Int64,
  size: Int64,
  accessed: Int64,
  modified: Int64,
  changed: Int64,
}

Information about the file that a FileDescriptor refers to.

File.DirectoryEntry

1
2
3
4
5

record DirectoryEntry {
  inode: Int64,
  filetype: Filetype,
  path: String,
}

An entry in a directory.

File.Prestat

1
2
3
4
5
6

enum Prestat {
  Dir{
    prefix: String,
    fd: FileDescriptor,
  },
}

Information about a preopened directory

Values

Functions and constants included in the File module.

File.stdin

1

stdin : FileDescriptor

The FileDescriptor for stdin.

File.stdout

1

stdout : FileDescriptor

The FileDescriptor for stdout.

File.stderr

1

stderr : FileDescriptor

The FileDescriptor for stderr.

File.pathOpen

1
2
3
4
5

pathOpen :
  (dirFd: FileDescriptor, dirFlags: List<LookupFlag>, path: String,
   openFlags: List<OpenFlag>, rights: List<Rights>,
   rightsInheriting: List<Rights>, flags: List<FdFlag>) =>
   Result<FileDescriptor, Exception>

Open a file or directory.

Parameters:

Returns:

File.fdRead

1
2

fdRead :
  (fd: FileDescriptor, size: Number) => Result<(Bytes, Number), Exception>

Read from a file descriptor.

Parameters:

Returns:

File.fdPread

1
2
3

fdPread :
  (fd: FileDescriptor, offset: Int64, size: Number) =>
   Result<(Bytes, Number), Exception>

Read from a file descriptor without updating the file descriptor’s offset.

Parameters:

Returns:

File.fdPrestatGet

1

fdPrestatGet : (fd: FileDescriptor) => Result<Prestat, Exception>

Get information about a preopened directory.

Parameters:

Returns:

File.fdWrite

1

fdWrite : (fd: FileDescriptor, data: Bytes) => Result<Number, Exception>

Write to a file descriptor.

Parameters:

Returns:

File.fdPwrite

1
2
3

fdPwrite :
  (fd: FileDescriptor, data: Bytes, offset: Int64) =>
   Result<Number, Exception>

Write to a file descriptor without updating the file descriptor’s offset.

Parameters:

Returns:

File.fdAllocate

1
2

fdAllocate :
  (fd: FileDescriptor, offset: Int64, size: Int64) => Result<Void, Exception>

Allocate space within a file.

Parameters:

Returns:

File.fdClose

1

fdClose : (fd: FileDescriptor) => Result<Void, Exception>

Close a file descriptor.

Parameters:

Returns:

File.fdDatasync

1

fdDatasync : (fd: FileDescriptor) => Result<Void, Exception>

Synchronize the data of a file to disk.

Parameters:

Returns:

File.fdSync

1

fdSync : (fd: FileDescriptor) => Result<Void, Exception>

Synchronize the data and metadata of a file to disk.

Parameters:

Returns:

File.fdStats

1

fdStats : (fd: FileDescriptor) => Result<Stats, Exception>

Retrieve information about a file descriptor.

Parameters:

Returns:

File.fdSetFlags

1
2

fdSetFlags :
  (fd: FileDescriptor, flags: List<FdFlag>) => Result<Void, Exception>

Update the flags associated with a file descriptor.

Parameters:

Returns:

File.fdSetRights

1
2
3

fdSetRights :
  (fd: FileDescriptor, rights: List<Rights>, rightsInheriting: List<Rights>) =>
   Result<Void, Exception>

Update the rights associated with a file descriptor.

Parameters:

Returns:

File.fdFilestats

1

fdFilestats : (fd: FileDescriptor) => Result<Filestats, Exception>

Retrieve information about a file.

Parameters:

Returns:

File.fdSetSize

1

fdSetSize : (fd: FileDescriptor, size: Int64) => Result<Void, Exception>

Set (truncate) the size of a file.

Parameters:

Returns:

File.fdSetAccessTime

1
2

fdSetAccessTime :
  (fd: FileDescriptor, timestamp: Int64) => Result<Void, Exception>

Set the access (created) time of a file.

Parameters:

Returns:

File.fdSetAccessTimeNow

1

fdSetAccessTimeNow : (fd: FileDescriptor) => Result<Void, Exception>

Set the access (created) time of a file to the current time.

Parameters:

Returns:

File.fdSetModifiedTime

1
2

fdSetModifiedTime :
  (fd: FileDescriptor, timestamp: Int64) => Result<Void, Exception>

Set the modified time of a file.

Parameters:

Returns:

File.fdSetModifiedTimeNow

1

fdSetModifiedTimeNow : (fd: FileDescriptor) => Result<Void, Exception>

Set the modified time of a file to the current time.

Parameters:

Returns:

File.fdReaddir

1

fdReaddir : (fd: FileDescriptor) => Result<Array<DirectoryEntry>, Exception>

Read the entires of a directory.

Parameters:

Returns:

File.fdRenumber

1
2

fdRenumber :
  (fromFd: FileDescriptor, toFd: FileDescriptor) => Result<Void, Exception>

Atomically replace a file descriptor by renumbering another file descriptor.

Parameters:

Returns:

File.fdSeek

1
2
3

fdSeek :
  (fd: FileDescriptor, offset: Int64, whence: Whence) =>
   Result<Int64, Exception>

Update a file descriptor’s offset.

Parameters:

Returns:

File.fdTell

1

fdTell : (fd: FileDescriptor) => Result<Int64, Exception>

Read a file descriptor’s offset.

Parameters:

Returns:

File.pathCreateDirectory

1
2

pathCreateDirectory :
  (fd: FileDescriptor, path: String) => Result<Void, Exception>

Create a directory.

Parameters:

Returns:

File.pathFilestats

1
2
3

pathFilestats :
  (fd: FileDescriptor, dirFlags: List<LookupFlag>, path: String) =>
   Result<Filestats, Exception>

Retrieve information about a file.

Parameters:

Returns:

File.pathSetAccessTime

1
2
3

pathSetAccessTime :
  (fd: FileDescriptor, dirFlags: List<LookupFlag>, path: String,
   timestamp: Int64) => Result<Void, Exception>

Set the access (created) time of a file.

Parameters:

Returns:

File.pathSetAccessTimeNow

1
2
3

pathSetAccessTimeNow :
  (fd: FileDescriptor, dirFlags: List<LookupFlag>, path: String) =>
   Result<Void, Exception>

Set the access (created) time of a file to the current time.

Parameters:

Returns:

File.pathSetModifiedTime

1
2
3

pathSetModifiedTime :
  (fd: FileDescriptor, dirFlags: List<LookupFlag>, path: String,
   timestamp: Int64) => Result<Void, Exception>

Set the modified time of a file.

Parameters:

Returns:

File.pathSetModifiedTimeNow

1
2
3

pathSetModifiedTimeNow :
  (fd: FileDescriptor, dirFlags: List<LookupFlag>, path: String) =>
   Result<Void, Exception>

Set the modified time of a file to the current time.

Parameters:

Returns:

File.pathLink

1
2
3
4

pathLink :
  (sourceFd: FileDescriptor, dirFlags: List<LookupFlag>, sourcePath: 
   String, targetFd: FileDescriptor, targetPath: String) =>
   Result<Void, Exception>

Create a hard link.

Parameters:

Returns:

File.pathSymlink

1
2
3

pathSymlink :
  (fd: FileDescriptor, sourcePath: String, targetPath: String) =>
   Result<Void, Exception>

Create a symlink.

Parameters:

Returns:

File.pathUnlink

1

pathUnlink : (fd: FileDescriptor, path: String) => Result<Void, Exception>

Unlink a file.

Parameters:

Returns:

File.pathReadlink

1
2
3

pathReadlink :
  (fd: FileDescriptor, path: String, size: Number) =>
   Result<(String, Number), Exception>

Read the contents of a symbolic link.

Parameters:

Returns:

File.pathRemoveDirectory

1
2

pathRemoveDirectory :
  (fd: FileDescriptor, path: String) => Result<Void, Exception>

Remove a directory.

Parameters:

Returns:

File.pathRename

1
2
3

pathRename :
  (sourceFd: FileDescriptor, sourcePath: String, targetFd: FileDescriptor,
   targetPath: String) => Result<Void, Exception>

Rename a file or directory.

Parameters:

Returns:

File.open

1
2
3
4

open :
  (path: String, openFlags: List<OpenFlag>, rights: List<Rights>,
   rightsInheriting: List<Rights>, flags: List<FdFlag>) =>
   Result<FileDescriptor, Exception>

Similar to pathOpen, but resolves the path relative to preopened directories.

Parameters:

Returns: