ESC
No recent searches
Search by
Standard Library  /  File

Grain Docs

Welcome to Grain! Editor Setup Getting Grain

The Guide

Hello World The Basics Conditionals Functions Shadowing and Mutation Loops Lists and arrays Custom Data Types Modules Pattern Matching

Reference

Building for Production Built-in Types The Grain CLI Graindoc

Standard Library

Pervasives BigInt Array Buffer Bytes Char Exception Float32 Float64 Hash Int16 Int32 Int64 Int8 Json List Map Marshal Number Option Path PriorityQueue Queue Random Range Rational Regex Result Stack Set String Uint16 Uint32 Uint64 Uint8 Uri wasi / File wasi / Process wasi / Random wasi / Time

File

Utilities for accessing the filesystem & working with files.

Edit on GitHub

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

Types

Type declarations included in the File module.

File.FileDescriptor

enum FileDescriptor {
  FileDescriptor(Number),
}

Represents a handle to an open file on the system.

File.LookupFlag

enum LookupFlag {
  SymlinkFollow,
}

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

Variants:

SymlinkFollow

Follow symlinks

File.OpenFlag

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.

File.Rights

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:

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).

File.FdFlag

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.

File.Filetype

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.

File.Whence

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.

File.Stats

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

Information about a FileDescriptor.

File.Filestats

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

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

An entry in a directory.

File.Prestat

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

Information about a preopened directory

Values

Functions and constants included in the File module.

File.stdin

stdin : FileDescriptor

The FileDescriptor for stdin.

File.stdout

stdout : FileDescriptor

The FileDescriptor for stdout.

File.stderr

stderr : FileDescriptor

The FileDescriptor for stderr.

File.pathOpen

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:

dirFd: The directory in which path resolution starts
dirFlags: Flags which affect path resolution
path: The path to the file or directory
openFlags: Flags that decide how the path will be opened
rights: The rights that dictate what may be done with the returned file descriptor
rightsInheriting: The rights that dictate what may be done with file descriptors derived from this file descriptor
flags: Flags which affect read/write operations on this file descriptor

Returns:

Result<FileDescriptor, Exception>: Ok(fd) of the opened file or directory if successful or Err(exception) otherwise

File.fdRead

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

Read from a file descriptor.

Parameters:

fd: The file descriptor to read from
size: The maximum number of bytes to read from the file descriptor

Returns:

Result<(Bytes, Number), Exception>: Ok((contents, numBytes)) of bytes read and the number of bytes read if successful or Err(exception) otherwise

File.fdPread

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

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

Parameters:

fd: The file descriptor to read from
offset: The position within the file to begin reading
size: The maximum number of bytes to read from the file descriptor

Returns:

Result<(Bytes, Number), Exception>: Ok((contents, numBytes)) of bytes read and the number of bytes read if successful or Err(exception) otherwise

File.fdPrestatGet

Added in 0.6.0 No other changes yet. 
fdPrestatGet : (fd: FileDescriptor) => Result<Prestat, Exception>

Get information about a preopened directory.

Parameters:

fd: The file descriptor to check

Returns:

Result<Prestat, Exception>: Ok(Dir{prefix, fd}) if successful or Err(exception) otherwise

File.fdWrite

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

Write to a file descriptor.

Parameters:

fd: The file descriptor to which data will be written
data: The data to be written

Returns:

Result<Number, Exception>: Ok(numBytes) of the number of bytes written if successful or Err(Exception) otherwise

File.fdPwrite

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

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

Parameters:

fd: The file descriptor to which data will be written
data: The data to be written
offset: The position within the file to begin writing

Returns:

Result<Number, Exception>: Ok(numBytes) of the number of bytes written if successful or Err(exception) otherwise

File.fdAllocate

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

Allocate space within a file.

Parameters:

fd: The file descriptor in which space will be allocated
offset: The position within the file to begin writing
size: The number of bytes to allocate

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.fdClose

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

Close a file descriptor.

Parameters:

fd: The file descriptor to close

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.fdDatasync

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

Synchronize the data of a file to disk.

Parameters:

fd: The file descriptor to synchronize

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.fdSync

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

Synchronize the data and metadata of a file to disk.

Parameters:

fd: The file descriptor to synchronize

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.fdStats

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

Retrieve information about a file descriptor.

Parameters:

fd: The file descriptor of which to retrieve information

Returns:

Result<Stats, Exception>: Ok(stats) of the Stats associated with the file descriptor if successful or Err(exception) otherwise

File.fdSetFlags

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

Update the flags associated with a file descriptor.

Parameters:

fd: The file descriptor to update flags
flags: The flags to apply to the file descriptor

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.fdSetRights

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

Update the rights associated with a file descriptor.

Parameters:

fd: The file descriptor to update rights
rights: Rights to apply to the file descriptor
rightsInheriting: Inheriting rights to apply to the file descriptor

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.fdFilestats

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

Retrieve information about a file.

Parameters:

fd: The file descriptor of the file to retrieve information

Returns:

Result<Filestats, Exception>: Ok(info) of the Filestats associated with the file descriptor if successful or Err(exception) otherwise

File.fdSetSize

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

Set (truncate) the size of a file.

Parameters:

fd: The file descriptor of the file to truncate
size: The number of bytes to retain in the file

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.fdSetAccessTime

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

Set the access (created) time of a file.

Parameters:

fd: The file descriptor of the file to update
timestamp: The time to set

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.fdSetAccessTimeNow

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

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

Parameters:

fd: The file descriptor of the file to update

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.fdSetModifiedTime

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

Set the modified time of a file.

Parameters:

fd: The file descriptor of the file to update
timestamp: The time to set

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.fdSetModifiedTimeNow

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

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

Parameters:

fd: The file descriptor of the file to update

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.fdReaddir

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

Read the entires of a directory.

Parameters:

fd: The directory to read

Returns:

Result<Array<DirectoryEntry>, Exception>: Ok(dirEntries) of an array of DirectoryEntry for each entry in the directory if successful or Err(exception) otherwise

File.fdRenumber

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

Atomically replace a file descriptor by renumbering another file descriptor.

Parameters:

fromFd: The file descriptor to renumber
toFd: The file descriptor to overwrite

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.fdSeek

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

Update a file descriptor’s offset.

Parameters:

fd: The file descriptor to operate on
offset: The number of bytes to move the offset
whence: The location from which the offset is relative

Returns:

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

File.fdTell

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

Read a file descriptor’s offset.

Parameters:

fd: The file descriptor to read the offset

Returns:

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

File.pathCreateDirectory

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

Create a directory.

Parameters:

fd: The file descriptor of the directory in which path resolution starts
path: The path to the new directory

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.pathFilestats

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

Retrieve information about a file.

Parameters:

fd: The file descriptor of the directory in which path resolution starts
dirFlags: Flags which affect path resolution
path: The path to retrieve information about

Returns:

Result<Filestats, Exception>: Ok(info) of the Filestats associated with the file descriptor if successful or Err(exception) otherwise

File.pathSetAccessTime

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

Set the access (created) time of a file.

Parameters:

fd: The file descriptor of the directory in which path resolution starts
dirFlags: Flags which affect path resolution
path: The path to set the time
timestamp: The time to set

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.pathSetAccessTimeNow

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

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

Parameters:

fd: The file descriptor of the directory in which path resolution starts
dirFlags: Flags which affect path resolution
path: The path to set the time

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.pathSetModifiedTime

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

Set the modified time of a file.

Parameters:

fd: The file descriptor of the directory in which path resolution starts
dirFlags: Flags which affect path resolution
path: The path to set the time
timestamp: The time to set

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.pathSetModifiedTimeNow

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

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

Parameters:

fd: The file descriptor of the directory in which path resolution starts
dirFlags: Flags which affect path resolution
path: The path to set the time

Returns:

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:

sourceFd: The file descriptor of the directory in which the source path resolution starts
dirFlags: Flags which affect path resolution
sourcePath: The path to the source of the link
targetFd: The file descriptor of the directory in which the target path resolution starts
targetPath: The path to the target of the link

Returns:

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:

fd: The file descriptor of the directory in which path resolution starts
sourcePath: The path to the source of the link
targetPath: The path to the target of the link

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise
pathUnlink : (fd: FileDescriptor, path: String) => Result<Void, Exception>

Unlink a file.

Parameters:

fd: The file descriptor of the directory in which path resolution starts
path: The path of the file to unlink

Returns:

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:

fd: The file descriptor of the directory in which path resolution starts
path: The path to the symlink
size: The number of bytes to read

Returns:

Result<(String, Number), Exception>: Ok((contents, numBytes)) of the bytes read and the number of bytes read if successful or Err(exception) otherwise

File.pathRemoveDirectory

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

Remove a directory.

Parameters:

fd: The file descriptor of the directory in which path resolution starts
path: The path to the directory to remove

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.pathRename

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

Rename a file or directory.

Parameters:

sourceFd: The file descriptor of the directory in which the source path resolution starts
sourcePath: The path of the file to rename
targetFd: The file descriptor of the directory in which the target path resolution starts
targetPath: The new path of the file

Returns:

Result<Void, Exception>: Ok(void) if successful or Err(exception) otherwise

File.open

Added in 0.6.0 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:

path: The path to the file or directory
openFlags: Flags that decide how the path will be opened
rights: The rights that dictate what may be done with the returned file descriptor
rightsInheriting: The rights that dictate what may be done with file descriptors derived from this file descriptor
flags: Flags which affect read/write operations on this file descriptor

Returns:

Result<FileDescriptor, Exception>: Ok(fd) of the opened file or directory if successful or Err(exception) otherwise
Uri Process

Sign up for farm-to-inbox developer news

You can unsubscribe at any time. Read our privacy policy.

Copyright © 2024 The Grain Programming Language