title |
---|
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.
from "wasi/file" include File
Type declarations included in the File module.
enum FileDescriptor {
FileDescriptor(Number),
}
Represents a handle to an open file on the system.
enum LookupFlag {
SymlinkFollow,
}
Flags that determine how paths should be resolved when looking up a file or directory.
Variants:
SymlinkFollow
Follow symlinks
enum OpenFlag {
Create,
Directory,
Exclusive,
Truncate,
}
Flags that determine how a file or directory should be opened.
Variants:
Create
Create file if it does not exist.
Directory
Fail if not a directory.
Exclusive
Fail if file already exists.
Truncate
Truncate file to size 0.
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 FileDescriptor
s should inherit from it.
Variants:
FdDatasync
The right to invoke fdDatasync
.
If PathOpen
is set, includes the right to invoke
pathOpen
with FdFlag::Dsync
.
FdRead
The right to invoke fdRead
.
If Rights::FdSeek
is set, includes the right to invoke fdPread
.
FdSeek
The right to invoke fdSeek
. This flag implies Rights::FdTell
.
FdSetFlags
The right to invoke fdSetFlags
.
FdSync
The right to invoke fdSync
.
If PathOpen
is set, includes the right to invoke
pathOpen
with FdFlag::Rsync
and FdFlag::Dsync
.
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
.
FdWrite
The right to invoke fdWrite
.
If Rights::FdSeek
is set, includes the right to invoke fdPwrite
.
FdAdvise
The right to invoke fdAdvise
.
FdAllocate
The right to invoke fdAllocate
.
PathCreateDirectory
The right to invoke pathCreateDirectory
.
PathCreateFile
If PathOpen
is set, the right to invoke pathOpen
with OpenFlag::Create
.
PathLinkSource
The right to invoke pathLink
with the file descriptor as the
source directory.
PathLinkTarget
The right to invoke pathLink
with the file descriptor as the
target directory.
PathOpen
The right to invoke pathOpen
.
FdReaddir
The right to invoke fdReaddir
.
PathReadlink
The right to invoke pathReadlink
.
PathRenameSource
The right to invoke pathRename
with the file descriptor as the source directory.
PathRenameTarget
The right to invoke pathRename
with the file descriptor as the target directory.
PathFilestats
The right to invoke pathFilestats
.
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
.
PathSetTimes
The right to invoke pathSetAccessTime
, pathSetAccessTimeNow
, pathSetModifiedTime
, or pathSetModifiedTimeNow
.
FdFilestats
The right to invoke fdFilestats
.
FdSetSize
The right to invoke fdSetSize
.
FdSetTimes
The right to invoke fdSetAccessTime
, fdSetAccessTimeNow
, fdSetModifiedTime
, or fdSetModifiedTimeNow
.
PathSymlink
The right to invoke pathSymlink
.
PathRemoveDirectory
The right to invoke pathRemoveDirectory
.
PathUnlinkFile
The right to invoke pathUnlinkFile
.
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
.
SockShutdown
The right to invoke sockShutdown
(not yet implemented).
enum FdFlag {
Append,
Dsync,
Nonblock,
Rsync,
Sync,
}
Flags that determine the mode(s) that a FileDescriptor
operates in.
Variants:
Append
Append mode: Data written to the file is always appended to the file's end.
Dsync
Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized.
Nonblock
Non-blocking mode.
Rsync
Synchronized read I/O operations.
enum Filetype {
Unknown,
BlockDevice,
CharacterDevice,
Directory,
RegularFile,
SocketDatagram,
SocketStream,
SymbolicLink,
}
The type of file a FileDescriptor
refers to.
Variants:
Unknown
The type of the file descriptor or file is unknown or is different from any of the other types specified.
BlockDevice
The file descriptor or file refers to a block device inode.
CharacterDevice
The file descriptor or file refers to a character device inode.
Directory
The file descriptor or file refers to a directory inode.
RegularFile
The file descriptor or file refers to a regular file inode.
SocketDatagram
The file descriptor or file refers to a datagram socket.
SocketStream
The file descriptor or file refers to a byte-stream socket.
SymbolicLink
The file refers to a symbolic link inode.
enum Whence {
Set,
Current,
End,
}
Flags that determine where seeking should begin in a file.
Variants:
Set
Seek relative to start-of-file.
Current
Seek relative to current position.
End
Seek relative to end-of-file.
record Stats {
filetype: Filetype,
flags: List<FdFlag>,
rights: List<Rights>,
rightsInheriting: List<Rights>,
}
Information about a FileDescriptor
.
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.
record DirectoryEntry {
inode: Int64,
filetype: Filetype,
path: String,
}
An entry in a directory.
enum Prestat {
Dir{
prefix: String,
fd: FileDescriptor,
},
}
Information about a preopened directory
Functions and constants included in the File module.
stdin : FileDescriptor
The FileDescriptor
for stdin
.
stdout : FileDescriptor
The FileDescriptor
for stdout
.
stderr : FileDescriptor
The FileDescriptor
for stderr
.
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:
param | type | description |
---|---|---|
dirFd |
FileDescriptor |
The directory in which path resolution starts |
dirFlags |
List<LookupFlag> |
Flags which affect path resolution |
path |
String |
The path to the file or directory |
openFlags |
List<OpenFlag> |
Flags that decide how the path will be opened |
rights |
List<Rights> |
The rights that dictate what may be done with the returned file descriptor |
rightsInheriting |
List<Rights> |
The rights that dictate what may be done with file descriptors derived from this file descriptor |
flags |
List<FdFlag> |
Flags which affect read/write operations on this file descriptor |
Returns:
type | description |
---|---|
Result<FileDescriptor, Exception> |
Ok(fd) of the opened file or directory if successful or Err(exception) otherwise |
fdRead :
(fd: FileDescriptor, size: Number) => Result<(Bytes, Number), Exception>
Read from a file descriptor.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor to read from |
size |
Number |
The maximum number of bytes to read from the file descriptor |
Returns:
type | description |
---|---|
Result<(Bytes, Number), Exception> |
Ok((contents, numBytes)) of bytes read and the number of bytes read if successful or Err(exception) otherwise |
fdPread :
(fd: FileDescriptor, offset: Int64, size: Number) =>
Result<(Bytes, Number), Exception>
Read from a file descriptor without updating the file descriptor's offset.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor to read from |
offset |
Int64 |
The position within the file to begin reading |
size |
Number |
The maximum number of bytes to read from the file descriptor |
Returns:
type | description |
---|---|
Result<(Bytes, Number), Exception> |
Ok((contents, numBytes)) of bytes read and the number of bytes read if successful or Err(exception) otherwise |
Added in next
No other changes yet.
fdPrestatGet : (fd: FileDescriptor) => Result<Prestat, Exception>
Get information about a preopened directory.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor to check |
Returns:
type | description |
---|---|
Result<Prestat, Exception> |
Ok(Dir{prefix, fd}) if successful or Err(exception) otherwise |
fdWrite : (fd: FileDescriptor, data: Bytes) => Result<Number, Exception>
Write to a file descriptor.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor to which data will be written |
data |
Bytes |
The data to be written |
Returns:
type | description |
---|---|
Result<Number, Exception> |
Ok(numBytes) of the number of bytes written if successful or Err(Exception) otherwise |
fdPwrite :
(fd: FileDescriptor, data: Bytes, offset: Int64) =>
Result<Number, Exception>
Write to a file descriptor without updating the file descriptor's offset.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor to which data will be written |
data |
Bytes |
The data to be written |
offset |
Int64 |
The position within the file to begin writing |
Returns:
type | description |
---|---|
Result<Number, Exception> |
Ok(numBytes) of the number of bytes written if successful or Err(exception) otherwise |
fdAllocate :
(fd: FileDescriptor, offset: Int64, size: Int64) => Result<Void, Exception>
Allocate space within a file.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor in which space will be allocated |
offset |
Int64 |
The position within the file to begin writing |
size |
Int64 |
The number of bytes to allocate |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
fdClose : (fd: FileDescriptor) => Result<Void, Exception>
Close a file descriptor.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor to close |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
fdDatasync : (fd: FileDescriptor) => Result<Void, Exception>
Synchronize the data of a file to disk.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor to synchronize |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
fdSync : (fd: FileDescriptor) => Result<Void, Exception>
Synchronize the data and metadata of a file to disk.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor to synchronize |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
fdStats : (fd: FileDescriptor) => Result<Stats, Exception>
Retrieve information about a file descriptor.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of which to retrieve information |
Returns:
type | description |
---|---|
Result<Stats, Exception> |
Ok(stats) of the Stats associated with the file descriptor if successful or Err(exception) otherwise |
fdSetFlags :
(fd: FileDescriptor, flags: List<FdFlag>) => Result<Void, Exception>
Update the flags associated with a file descriptor.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor to update flags |
flags |
List<FdFlag> |
The flags to apply to the file descriptor |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
fdSetRights :
(fd: FileDescriptor, rights: List<Rights>, rightsInheriting: List<Rights>) =>
Result<Void, Exception>
Update the rights associated with a file descriptor.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor to update rights |
rights |
List<Rights> |
Rights to apply to the file descriptor |
rightsInheriting |
List<Rights> |
Inheriting rights to apply to the file descriptor |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
fdFilestats : (fd: FileDescriptor) => Result<Filestats, Exception>
Retrieve information about a file.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of the file to retrieve information |
Returns:
type | description |
---|---|
Result<Filestats, Exception> |
Ok(info) of the Filestats associated with the file descriptor if successful or Err(exception) otherwise |
fdSetSize : (fd: FileDescriptor, size: Int64) => Result<Void, Exception>
Set (truncate) the size of a file.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of the file to truncate |
size |
Int64 |
The number of bytes to retain in the file |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
fdSetAccessTime :
(fd: FileDescriptor, timestamp: Int64) => Result<Void, Exception>
Set the access (created) time of a file.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of the file to update |
timestamp |
Int64 |
The time to set |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
fdSetAccessTimeNow : (fd: FileDescriptor) => Result<Void, Exception>
Set the access (created) time of a file to the current time.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of the file to update |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
fdSetModifiedTime :
(fd: FileDescriptor, timestamp: Int64) => Result<Void, Exception>
Set the modified time of a file.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of the file to update |
timestamp |
Int64 |
The time to set |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
fdSetModifiedTimeNow : (fd: FileDescriptor) => Result<Void, Exception>
Set the modified time of a file to the current time.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of the file to update |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
fdReaddir : (fd: FileDescriptor) => Result<Array<DirectoryEntry>, Exception>
Read the entires of a directory.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The directory to read |
Returns:
type | description |
---|---|
Result<Array<DirectoryEntry>, Exception> |
Ok(dirEntries) of an array of DirectoryEntry for each entry in the directory if successful or Err(exception) otherwise |
fdRenumber :
(fromFd: FileDescriptor, toFd: FileDescriptor) => Result<Void, Exception>
Atomically replace a file descriptor by renumbering another file descriptor.
Parameters:
param | type | description |
---|---|---|
fromFd |
FileDescriptor |
The file descriptor to renumber |
toFd |
FileDescriptor |
The file descriptor to overwrite |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
fdSeek :
(fd: FileDescriptor, offset: Int64, whence: Whence) =>
Result<Int64, Exception>
Update a file descriptor's offset.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor to operate on |
offset |
Int64 |
The number of bytes to move the offset |
whence |
Whence |
The location from which the offset is relative |
Returns:
type | description |
---|---|
Result<Int64, Exception> |
Ok(offset) of the new offset of the file descriptor, relative to the start of the file, if successful or Err(exception) otherwise |
fdTell : (fd: FileDescriptor) => Result<Int64, Exception>
Read a file descriptor's offset.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor to read the offset |
Returns:
type | description |
---|---|
Result<Int64, Exception> |
Ok(offset) of the offset of the file descriptor, relative to the start of the file, if successful or Err(exception) otherwise |
pathCreateDirectory :
(fd: FileDescriptor, path: String) => Result<Void, Exception>
Create a directory.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of the directory in which path resolution starts |
path |
String |
The path to the new directory |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
pathFilestats :
(fd: FileDescriptor, dirFlags: List<LookupFlag>, path: String) =>
Result<Filestats, Exception>
Retrieve information about a file.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of the directory in which path resolution starts |
dirFlags |
List<LookupFlag> |
Flags which affect path resolution |
path |
String |
The path to retrieve information about |
Returns:
type | description |
---|---|
Result<Filestats, Exception> |
Ok(info) of the Filestats associated with the file descriptor if successful or Err(exception) otherwise |
pathSetAccessTime :
(fd: FileDescriptor, dirFlags: List<LookupFlag>, path: String,
timestamp: Int64) => Result<Void, Exception>
Set the access (created) time of a file.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of the directory in which path resolution starts |
dirFlags |
List<LookupFlag> |
Flags which affect path resolution |
path |
String |
The path to set the time |
timestamp |
Int64 |
The time to set |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
pathSetAccessTimeNow :
(fd: FileDescriptor, dirFlags: List<LookupFlag>, path: String) =>
Result<Void, Exception>
Set the access (created) time of a file to the current time.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of the directory in which path resolution starts |
dirFlags |
List<LookupFlag> |
Flags which affect path resolution |
path |
String |
The path to set the time |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
pathSetModifiedTime :
(fd: FileDescriptor, dirFlags: List<LookupFlag>, path: String,
timestamp: Int64) => Result<Void, Exception>
Set the modified time of a file.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of the directory in which path resolution starts |
dirFlags |
List<LookupFlag> |
Flags which affect path resolution |
path |
String |
The path to set the time |
timestamp |
Int64 |
The time to set |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
pathSetModifiedTimeNow :
(fd: FileDescriptor, dirFlags: List<LookupFlag>, path: String) =>
Result<Void, Exception>
Set the modified time of a file to the current time.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of the directory in which path resolution starts |
dirFlags |
List<LookupFlag> |
Flags which affect path resolution |
path |
String |
The path to set the time |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
pathLink :
(sourceFd: FileDescriptor, dirFlags: List<LookupFlag>, sourcePath:
String, targetFd: FileDescriptor, targetPath: String) =>
Result<Void, Exception>
Create a hard link.
Parameters:
param | type | description |
---|---|---|
sourceFd |
FileDescriptor |
The file descriptor of the directory in which the source path resolution starts |
dirFlags |
List<LookupFlag> |
Flags which affect path resolution |
sourcePath |
String |
The path to the source of the link |
targetFd |
FileDescriptor |
The file descriptor of the directory in which the target path resolution starts |
targetPath |
String |
The path to the target of the link |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
pathSymlink :
(fd: FileDescriptor, sourcePath: String, targetPath: String) =>
Result<Void, Exception>
Create a symlink.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of the directory in which path resolution starts |
sourcePath |
String |
The path to the source of the link |
targetPath |
String |
The path to the target of the link |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
pathUnlink : (fd: FileDescriptor, path: String) => Result<Void, Exception>
Unlink a file.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of the directory in which path resolution starts |
path |
String |
The path of the file to unlink |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
pathReadlink :
(fd: FileDescriptor, path: String, size: Number) =>
Result<(String, Number), Exception>
Read the contents of a symbolic link.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of the directory in which path resolution starts |
path |
String |
The path to the symlink |
size |
Number |
The number of bytes to read |
Returns:
type | description |
---|---|
Result<(String, Number), Exception> |
Ok((contents, numBytes)) of the bytes read and the number of bytes read if successful or Err(exception) otherwise |
pathRemoveDirectory :
(fd: FileDescriptor, path: String) => Result<Void, Exception>
Remove a directory.
Parameters:
param | type | description |
---|---|---|
fd |
FileDescriptor |
The file descriptor of the directory in which path resolution starts |
path |
String |
The path to the directory to remove |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
pathRename :
(sourceFd: FileDescriptor, sourcePath: String, targetFd: FileDescriptor,
targetPath: String) => Result<Void, Exception>
Rename a file or directory.
Parameters:
param | type | description |
---|---|---|
sourceFd |
FileDescriptor |
The file descriptor of the directory in which the source path resolution starts |
sourcePath |
String |
The path of the file to rename |
targetFd |
FileDescriptor |
The file descriptor of the directory in which the target path resolution starts |
targetPath |
String |
The new path of the file |
Returns:
type | description |
---|---|
Result<Void, Exception> |
Ok(void) if successful or Err(exception) otherwise |
Added in next
No other changes yet.
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:
param | type | description |
---|---|---|
path |
String |
The path to the file or directory |
openFlags |
List<OpenFlag> |
Flags that decide how the path will be opened |
rights |
List<Rights> |
The rights that dictate what may be done with the returned file descriptor |
rightsInheriting |
List<Rights> |
The rights that dictate what may be done with file descriptors derived from this file descriptor |
flags |
List<FdFlag> |
Flags which affect read/write operations on this file descriptor |
Returns:
type | description |
---|---|
Result<FileDescriptor, Exception> |
Ok(fd) of the opened file or directory if successful or Err(exception) otherwise |