Skip to content

Latest commit

 

History

History
1403 lines (1403 loc) · 72.4 KB

example-world.md

File metadata and controls

1403 lines (1403 loc) · 72.4 KB
Raw

World example-world

  • Imports:
    • interface wasi:poll/poll
    • interface wasi:io/streams
    • interface wasi:clocks/wall-clock
    • interface wasi:filesystem/types
    • interface wasi:filesystem/preopens

Import interface wasi:poll/poll

A poll API intended to let users wait for I/O events on multiple handles at once.

Types

type pollable

u32

A "pollable" handle.

This is conceptually represents a stream<_, _>, or in other words, a stream that one can wait on, repeatedly, but which does not itself produce any data. It's temporary scaffolding until component-model's async features are ready.

And at present, it is a u32 instead of being an actual handle, until the wit-bindgen implementation of handles and resources is ready.

pollable lifetimes are not automatically managed. Users must ensure that they do not outlive the resource they reference.

This represents a resource.

Functions

drop-pollable: func

Dispose of the specified pollable, after which it may no longer be used.

Params

poll-oneoff: func

Poll for completion on a set of pollables.

The "oneoff" in the name refers to the fact that this function must do a linear scan through the entire list of subscriptions, which may be inefficient if the number is large and the same subscriptions are used many times. In the future, this is expected to be obsoleted by the component model async proposal, which will include a scalable waiting facility.

Note that the return type would ideally be list<bool>, but that would be more difficult to polyfill given the current state of wit-bindgen. See bytecodealliance/preview2-prototyping#11 (comment) for details. For now, we use zero to mean "not ready" and non-zero to mean "ready".

Params
Return values
  • list<u8>

Import interface wasi:io/streams

WASI I/O is an I/O abstraction API which is currently focused on providing stream types.

In the future, the component model is expected to add built-in stream types; when it does, they are expected to subsume this API.

Types

type pollable

pollable

#### `record stream-error`

An error type returned from a stream operation. Currently this doesn't provide any additional information.

Record Fields

type output-stream

u32

An output bytestream. In the future, this will be replaced by handle types.

This conceptually represents a stream<u8, _>. It's temporary scaffolding until component-model's async features are ready.

output-streams are non-blocking to the extent practical on underlying platforms. Except where specified otherwise, I/O operations also always return promptly, after the number of bytes that can be written promptly, which could even be zero. To wait for the stream to be ready to accept data, the subscribe-to-output-stream function to obtain a pollable which can be polled for using wasi_poll.

And at present, it is a u32 instead of being an actual handle, until the wit-bindgen implementation of handles and resources is ready.

This represents a resource.

type input-stream

u32

An input bytestream. In the future, this will be replaced by handle types.

This conceptually represents a stream<u8, _>. It's temporary scaffolding until component-model's async features are ready.

input-streams are non-blocking to the extent practical on underlying platforms. I/O operations always return promptly; if fewer bytes are promptly available than requested, they return the number of bytes promptly available, which could even be zero. To wait for data to be available, use the subscribe-to-input-stream function to obtain a pollable which can be polled for using wasi_poll.

And at present, it is a u32 instead of being an actual handle, until the wit-bindgen implementation of handles and resources is ready.

This represents a resource.

Functions

read: func

Read bytes from a stream.

This function returns a list of bytes containing the data that was read, along with a bool which, when true, indicates that the end of the stream was reached. The returned list will contain up to len bytes; it may return fewer than requested, but not more.

Once a stream has reached the end, subsequent calls to read or skip will always report end-of-stream rather than producing more data.

If len is 0, it represents a request to read 0 bytes, which should always succeed, assuming the stream hasn't reached its end yet, and return an empty list.

The len here is a u64, but some callees may not be able to allocate a buffer as large as that would imply. FIXME: describe what happens if allocation fails.

Params
Return values

blocking-read: func

Read bytes from a stream, with blocking.

This is similar to read, except that it blocks until at least one byte can be read.

Params
Return values

skip: func

Skip bytes from a stream.

This is similar to the read function, but avoids copying the bytes into the instance.

Once a stream has reached the end, subsequent calls to read or skip will always report end-of-stream rather than producing more data.

This function returns the number of bytes skipped, along with a bool indicating whether the end of the stream was reached. The returned value will be at most len; it may be less.

Params
Return values

blocking-skip: func

Skip bytes from a stream, with blocking.

This is similar to skip, except that it blocks until at least one byte can be consumed.

Params
Return values

subscribe-to-input-stream: func

Create a pollable which will resolve once either the specified stream has bytes available to read or the other end of the stream has been closed.

Params
Return values

drop-input-stream: func

Dispose of the specified input-stream, after which it may no longer be used.

Params

write: func

Write bytes to a stream.

This function returns a u64 indicating the number of bytes from buf that were written; it may be less than the full list.

Params
Return values

blocking-write: func

Write bytes to a stream, with blocking.

This is similar to write, except that it blocks until at least one byte can be written.

Params
Return values

write-zeroes: func

Write multiple zero bytes to a stream.

This function returns a u64 indicating the number of zero bytes that were written; it may be less than len.

Params
Return values

blocking-write-zeroes: func

Write multiple zero bytes to a stream, with blocking.

This is similar to write-zeroes, except that it blocks until at least one byte can be written.

Params
Return values

splice: func

Read from one stream and write to another.

This function returns the number of bytes transferred; it may be less than len.

Unlike other I/O functions, this function blocks until all the data read from the input stream has been written to the output stream.

Params
Return values

blocking-splice: func

Read from one stream and write to another, with blocking.

This is similar to splice, except that it blocks until at least one byte can be read.

Params
Return values

forward: func

Forward the entire contents of an input stream to an output stream.

This function repeatedly reads from the input stream and writes the data to the output stream, until the end of the input stream is reached, or an error is encountered.

Unlike other I/O functions, this function blocks until the end of the input stream is seen and all the data has been written to the output stream.

This function returns the number of bytes transferred.

Params
Return values

subscribe-to-output-stream: func

Create a pollable which will resolve once either the specified stream is ready to accept bytes or the other end of the stream has been closed.

Params
Return values

drop-output-stream: func

Dispose of the specified output-stream, after which it may no longer be used.

Params

Import interface wasi:clocks/wall-clock

WASI Wall Clock is a clock API intended to let users query the current time. The name "wall" makes an analogy to a "clock on the wall", which is not necessarily monotonic as it may be reset.

It is intended to be portable at least between Unix-family platforms and Windows.

A wall clock is a clock which measures the date and time according to some external reference.

External references may be reset, so this clock is not necessarily monotonic, making it unsuitable for measuring elapsed time.

It is intended for reporting the current date and time for humans.

Types

record datetime

A time and date in seconds plus nanoseconds.

Record Fields

Functions

now: func

Read the current value of the clock.

This clock is not monotonic, therefore calling this function repeatedly will not necessarily produce a sequence of non-decreasing values.

The returned timestamps represent the number of seconds since 1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, also known as Unix Time.

The nanoseconds field of the output is always less than 1000000000.

Return values

resolution: func

Query the resolution of the clock.

The nanoseconds field of the output is always less than 1000000000.

Return values

Import interface wasi:filesystem/types

WASI filesystem is a filesystem API primarily intended to let users run WASI programs that access their files on their existing filesystems, without significant overhead.

It is intended to be roughly portable between Unix-family platforms and Windows, though it does not hide many of the major differences.

Paths are passed as interface-type strings, meaning they must consist of a sequence of Unicode Scalar Values (USVs). Some filesystems may contain paths which are not accessible by this API.

The directory separator in WASI is always the forward-slash (/).

All paths in WASI are relative paths, and are interpreted relative to a descriptor referring to a base directory. If a path argument to any WASI function starts with /, or if any step of resolving a path, including .. and symbolic link steps, reaches a directory outside of the base directory, or reaches a symlink to an absolute or rooted path in the underlying filesystem, the function fails with error-code::not-permitted.

Types

type input-stream

input-stream

#### `type output-stream` [`output-stream`](#output_stream)

#### `type datetime` [`datetime`](#datetime)

#### `flags path-flags`

Flags determining the method of how paths are resolved.

Flags members
  • symlink-follow:

    As long as the resolved path corresponds to a symbolic link, it is expanded.

flags open-flags

Open flags used by open-at.

Flags members

  • create:

    Create file if it does not exist, similar to `O_CREAT` in POSIX.

  • directory:

    Fail if not a directory, similar to `O_DIRECTORY` in POSIX.

  • exclusive:

    Fail if file already exists, similar to `O_EXCL` in POSIX.

  • truncate:

    Truncate file to size 0, similar to `O_TRUNC` in POSIX.

flags modes

Permissions mode used by open-at, change-file-permissions-at, and similar.

Flags members

  • readable:

    True if the resource is considered readable by the containing filesystem.

  • writable:

    True if the resource is considered writable by the containing filesystem.

  • executable:

    True if the resource is considered executable by the containing filesystem. This does not apply to directories.

type link-count

u64

Number of hard links to an inode.

type inode

u64

Filesystem object serial number that is unique within its file system.

type filesize

u64

File size or length of a region within a file.

enum error-code

Error codes returned by functions, similar to errno in POSIX. Not all of these error codes are returned by the functions provided by this API; some are used in higher-level library layers, and others are provided merely for alignment with POSIX.

Enum Cases

  • access

    Permission denied, similar to `EACCES` in POSIX.

  • would-block

    Resource unavailable, or operation would block, similar to `EAGAIN` and `EWOULDBLOCK` in POSIX.

  • already

    Connection already in progress, similar to `EALREADY` in POSIX.

  • bad-descriptor

    Bad descriptor, similar to `EBADF` in POSIX.

  • busy

    Device or resource busy, similar to `EBUSY` in POSIX.

  • deadlock

    Resource deadlock would occur, similar to `EDEADLK` in POSIX.

  • quota

    Storage quota exceeded, similar to `EDQUOT` in POSIX.

  • exist

    File exists, similar to `EEXIST` in POSIX.

  • file-too-large

    File too large, similar to `EFBIG` in POSIX.

  • illegal-byte-sequence

    Illegal byte sequence, similar to `EILSEQ` in POSIX.

  • in-progress

    Operation in progress, similar to `EINPROGRESS` in POSIX.

  • interrupted

    Interrupted function, similar to `EINTR` in POSIX.

  • invalid

    Invalid argument, similar to `EINVAL` in POSIX.

  • io

    I/O error, similar to `EIO` in POSIX.

  • is-directory

    Is a directory, similar to `EISDIR` in POSIX.

  • loop

    Too many levels of symbolic links, similar to `ELOOP` in POSIX.

  • too-many-links

    Too many links, similar to `EMLINK` in POSIX.

  • message-size

    Message too large, similar to `EMSGSIZE` in POSIX.

  • name-too-long

    Filename too long, similar to `ENAMETOOLONG` in POSIX.

  • no-device

    No such device, similar to `ENODEV` in POSIX.

  • no-entry

    No such file or directory, similar to `ENOENT` in POSIX.

  • no-lock

    No locks available, similar to `ENOLCK` in POSIX.

  • insufficient-memory

    Not enough space, similar to `ENOMEM` in POSIX.

  • insufficient-space

    No space left on device, similar to `ENOSPC` in POSIX.

  • not-directory

    Not a directory or a symbolic link to a directory, similar to `ENOTDIR` in POSIX.

  • not-empty

    Directory not empty, similar to `ENOTEMPTY` in POSIX.

  • not-recoverable

    State not recoverable, similar to `ENOTRECOVERABLE` in POSIX.

  • unsupported

    Not supported, similar to `ENOTSUP` and `ENOSYS` in POSIX.

  • no-tty

    Inappropriate I/O control operation, similar to `ENOTTY` in POSIX.

  • no-such-device

    No such device or address, similar to `ENXIO` in POSIX.

  • overflow

    Value too large to be stored in data type, similar to `EOVERFLOW` in POSIX.

  • not-permitted

    Operation not permitted, similar to `EPERM` in POSIX.

  • pipe

    Broken pipe, similar to `EPIPE` in POSIX.

  • read-only

    Read-only file system, similar to `EROFS` in POSIX.

  • invalid-seek

    Invalid seek, similar to `ESPIPE` in POSIX.

  • text-file-busy

    Text file busy, similar to `ETXTBSY` in POSIX.

  • cross-device

    Cross-device link, similar to `EXDEV` in POSIX.

type directory-entry-stream

u32

A stream of directory entries.

This represents a stream of dir-entry.

type device

u64

Identifier for a device containing a file system. Can be used in combination with `inode` to uniquely identify a file or directory in the filesystem.

enum descriptor-type

The type of a filesystem object referenced by a descriptor.

Note: This was called filetype in earlier versions of WASI.

Enum Cases

  • unknown

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

  • block-device

    The descriptor refers to a block device inode.

  • character-device

    The descriptor refers to a character device inode.

  • directory

    The descriptor refers to a directory inode.

  • fifo

    The descriptor refers to a named pipe.

  • symbolic-link

    The file refers to a symbolic link inode.

  • regular-file

    The descriptor refers to a regular file inode.

  • socket

    The descriptor refers to a socket.

record directory-entry

A directory entry.

Record Fields

  • inode: option<inode>

    The serial number of the object referred to by this directory entry. May be none if the inode value is not known.

    When this is none, libc implementations might do an extra stat-at call to retrieve the inode number to fill their d_ino fields, so implementations which can set this to a non-none value should do so.

  • type: descriptor-type

    The type of the file referred to by this directory entry.

  • name: string

    The name of the object.

flags descriptor-flags

Descriptor flags.

Note: This was called fdflags in earlier versions of WASI.

Flags members

  • read:

    Read mode: Data can be read.

  • write:

    Write mode: Data can be written to.

  • non-blocking:

    Requests non-blocking operation.

    When this flag is enabled, functions may return immediately with an error-code::would-block error code in situations where they would otherwise block. However, this non-blocking behavior is not required. Implementations are permitted to ignore this flag and block. This is similar to O_NONBLOCK in POSIX.

  • file-integrity-sync:

    Request that writes be performed according to synchronized I/O file integrity completion. The data stored in the file and the file's metadata are synchronized. This is similar to `O_SYNC` in POSIX.

    The precise semantics of this operation have not yet been defined for WASI. At this time, it should be interpreted as a request, and not a requirement.

  • data-integrity-sync:

    Request that writes be performed according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized. This is similar to `O_DSYNC` in POSIX.

    The precise semantics of this operation have not yet been defined for WASI. At this time, it should be interpreted as a request, and not a requirement.

  • requested-write-sync:

    Requests that reads be performed at the same level of integrety requested for writes. This is similar to `O_RSYNC` in POSIX.

    The precise semantics of this operation have not yet been defined for WASI. At this time, it should be interpreted as a request, and not a requirement.

  • mutate-directory:

    Mutating directories mode: Directory contents may be mutated.

    When this flag is unset on a descriptor, operations using the descriptor which would create, rename, delete, modify the data or metadata of filesystem objects, or obtain another handle which would permit any of those, shall fail with error-code::read-only if they would otherwise succeed.

    This may only be set on directories.

type descriptor

u32

A descriptor is a reference to a filesystem object, which may be a file, directory, named pipe, special file, or other object on which filesystem calls may be made.

This represents a resource.

variant new-timestamp

When setting a timestamp, this gives the value to set it to.

Variant Cases

  • no-change

    Leave the timestamp set to its previous value.

  • now

    Set the timestamp to the current time of the system clock associated with the filesystem.

  • timestamp: datetime

    Set the timestamp to the given value.

record descriptor-stat

File attributes.

Note: This was called filestat in earlier versions of WASI.

Record Fields

enum advice

File or memory access pattern advisory information.

Enum Cases

  • normal

    The application has no advice to give on its behavior with respect to the specified data.

  • sequential

    The application expects to access the specified data sequentially from lower offsets to higher offsets.

  • random

    The application expects to access the specified data in a random order.

  • will-need

    The application expects to access the specified data in the near future.

  • dont-need

    The application expects that it will not access the specified data in the near future.

  • no-reuse

    The application expects to access the specified data once and then not reuse it thereafter.

variant access-type

Access type used by access-at.

Variant Cases

  • access: modes

    Test for readability, writeability, or executability.

  • exists

    Test whether the path exists.

Functions

read-via-stream: func

Return a stream for reading from a file, if available.

May fail with an error-code describing why the file cannot be read.

Multiple read, write, and append streams may be active on the same open file and they do not interfere with each other.

Note: This allows using read-stream, which is similar to read in POSIX.

Params
Return values

write-via-stream: func

Return a stream for writing to a file, if available.

May fail with an error-code describing why the file cannot be written.

Note: This allows using write-stream, which is similar to write in POSIX.

Params
Return values

append-via-stream: func

Return a stream for appending to a file, if available.

May fail with an error-code describing why the file cannot be appended.

Note: This allows using write-stream, which is similar to write with O_APPEND in in POSIX.

Params
Return values

advise: func

Provide file advisory information on a descriptor.

This is similar to posix_fadvise in POSIX.

Params
Return values

sync-data: func

Synchronize the data of a file to disk.

This function succeeds with no effect if the file descriptor is not opened for writing.

Note: This is similar to fdatasync in POSIX.

Params
Return values

get-flags: func

Get flags associated with a descriptor.

Note: This returns similar flags to fcntl(fd, F_GETFL) in POSIX.

Note: This returns the value that was the fs_flags value returned from fdstat_get in earlier versions of WASI.

Params
Return values

get-type: func

Get the dynamic type of a descriptor.

Note: This returns the same value as the type field of the fd-stat returned by stat, stat-at and similar.

Note: This returns similar flags to the st_mode & S_IFMT value provided by fstat in POSIX.

Note: This returns the value that was the fs_filetype value returned from fdstat_get in earlier versions of WASI.

Params
Return values

set-flags: func

Set status flags associated with a descriptor.

This function may only change the non-blocking flag.

Note: This is similar to fcntl(fd, F_SETFL, flags) in POSIX.

Note: This was called fd_fdstat_set_flags in earlier versions of WASI.

Params
Return values

set-size: func

Adjust the size of an open file. If this increases the file's size, the extra bytes are filled with zeros.

Note: This was called fd_filestat_set_size in earlier versions of WASI.

Params
Return values

set-times: func

Adjust the timestamps of an open file or directory.

Note: This is similar to futimens in POSIX.

Note: This was called fd_filestat_set_times in earlier versions of WASI.

Params
Return values

read: func

Read from a descriptor, without using and updating the descriptor's offset.

This function returns a list of bytes containing the data that was read, along with a bool which, when true, indicates that the end of the file was reached. The returned list will contain up to length bytes; it may return fewer than requested, if the end of the file is reached or if the I/O operation is interrupted.

In the future, this may change to return a stream<u8, error-code>.

Note: This is similar to pread in POSIX.

Params
Return values

write: func

Write to a descriptor, without using and updating the descriptor's offset.

It is valid to write past the end of a file; the file is extended to the extent of the write, with bytes between the previous end and the start of the write set to zero.

In the future, this may change to take a stream<u8, error-code>.

Note: This is similar to pwrite in POSIX.

Params
Return values

read-directory: func

Read directory entries from a directory.

On filesystems where directories contain entries referring to themselves and their parents, often named . and .. respectively, these entries are omitted.

This always returns a new stream which starts at the beginning of the directory. Multiple streams may be active on the same directory, and they do not interfere with each other.

Params
Return values

sync: func

Synchronize the data and metadata of a file to disk.

This function succeeds with no effect if the file descriptor is not opened for writing.

Note: This is similar to fsync in POSIX.

Params
Return values

create-directory-at: func

Create a directory.

Note: This is similar to mkdirat in POSIX.

Params
Return values

stat: func

Return the attributes of an open file or directory.

Note: This is similar to fstat in POSIX.

Note: This was called fd_filestat_get in earlier versions of WASI.

Params
Return values

stat-at: func

Return the attributes of a file or directory.

Note: This is similar to fstatat in POSIX.

Note: This was called path_filestat_get in earlier versions of WASI.

Params
Return values

set-times-at: func

Adjust the timestamps of a file or directory.

Note: This is similar to utimensat in POSIX.

Note: This was called path_filestat_set_times in earlier versions of WASI.

Params
Return values

link-at: func

Create a hard link.

Note: This is similar to linkat in POSIX.

Params
Return values

open-at: func

Open a file or directory.

The returned descriptor is not guaranteed to be the lowest-numbered descriptor not currently open/ it is randomized to prevent applications from depending on making assumptions about indexes, since this is error-prone in multi-threaded contexts. The returned descriptor is guaranteed to be less than 2**31.

If flags contains descriptor-flags::mutate-directory, and the base descriptor doesn't have descriptor-flags::mutate-directory set, open-at fails with error-code::read-only.

If flags contains write or mutate-directory, or open-flags contains truncate or create, and the base descriptor doesn't have descriptor-flags::mutate-directory set, open-at fails with error-code::read-only.

Note: This is similar to openat in POSIX.

Params
Return values

readlink-at: func

Read the contents of a symbolic link.

If the contents contain an absolute or rooted path in the underlying filesystem, this function fails with error-code::not-permitted.

Note: This is similar to readlinkat in POSIX.

Params
Return values

remove-directory-at: func

Remove a directory.

Return error-code::not-empty if the directory is not empty.

Note: This is similar to unlinkat(fd, path, AT_REMOVEDIR) in POSIX.

Params
Return values

rename-at: func

Rename a filesystem object.

Note: This is similar to renameat in POSIX.

Params
Return values

symlink-at: func

Create a symbolic link (also known as a "symlink").

If old-path starts with /, the function fails with error-code::not-permitted.

Note: This is similar to symlinkat in POSIX.

Params
Return values

access-at: func

Check accessibility of a filesystem path.

Check whether the given filesystem path names an object which is readable, writable, or executable, or whether it exists.

This does not a guarantee that subsequent accesses will succeed, as filesystem permissions may be modified asynchronously by external entities.

Note: This is similar to faccessat with the AT_EACCESS flag in POSIX.

Params
Return values

unlink-file-at: func

Unlink a filesystem object that is not a directory.

Return error-code::is-directory if the path refers to a directory. Note: This is similar to unlinkat(fd, path, 0) in POSIX.

Params
Return values

change-file-permissions-at: func

Change the permissions of a filesystem object that is not a directory.

Note that the ultimate meanings of these permissions is filesystem-specific.

Note: This is similar to fchmodat in POSIX.

Params
Return values

change-directory-permissions-at: func

Change the permissions of a directory.

Note that the ultimate meanings of these permissions is filesystem-specific.

Unlike in POSIX, the executable flag is not reinterpreted as a "search" flag. read on a directory implies readability and searchability, and execute is not valid for directories.

Note: This is similar to fchmodat in POSIX.

Params
Return values

lock-shared: func

Request a shared advisory lock for an open file.

This requests a shared lock; more than one shared lock can be held for a file at the same time.

If the open file has an exclusive lock, this function downgrades the lock to a shared lock. If it has a shared lock, this function has no effect.

This requests an advisory lock, meaning that the file could be accessed by other programs that don't hold the lock.

It is unspecified how shared locks interact with locks acquired by non-WASI programs.

This function blocks until the lock can be acquired.

Not all filesystems support locking; on filesystems which don't support locking, this function returns error-code::unsupported.

Note: This is similar to flock(fd, LOCK_SH) in Unix.

Params
Return values

lock-exclusive: func

Request an exclusive advisory lock for an open file.

This requests an exclusive lock; no other locks may be held for the file while an exclusive lock is held.

If the open file has a shared lock and there are no exclusive locks held for the file, this function upgrades the lock to an exclusive lock. If the open file already has an exclusive lock, this function has no effect.

This requests an advisory lock, meaning that the file could be accessed by other programs that don't hold the lock.

It is unspecified whether this function succeeds if the file descriptor is not opened for writing. It is unspecified how exclusive locks interact with locks acquired by non-WASI programs.

This function blocks until the lock can be acquired.

Not all filesystems support locking; on filesystems which don't support locking, this function returns error-code::unsupported.

Note: This is similar to flock(fd, LOCK_EX) in Unix.

Params
Return values

try-lock-shared: func

Request a shared advisory lock for an open file.

This requests a shared lock; more than one shared lock can be held for a file at the same time.

If the open file has an exclusive lock, this function downgrades the lock to a shared lock. If it has a shared lock, this function has no effect.

This requests an advisory lock, meaning that the file could be accessed by other programs that don't hold the lock.

It is unspecified how shared locks interact with locks acquired by non-WASI programs.

This function returns error-code::would-block if the lock cannot be acquired.

Not all filesystems support locking; on filesystems which don't support locking, this function returns error-code::unsupported.

Note: This is similar to flock(fd, LOCK_SH | LOCK_NB) in Unix.

Params
Return values

try-lock-exclusive: func

Request an exclusive advisory lock for an open file.

This requests an exclusive lock; no other locks may be held for the file while an exclusive lock is held.

If the open file has a shared lock and there are no exclusive locks held for the file, this function upgrades the lock to an exclusive lock. If the open file already has an exclusive lock, this function has no effect.

This requests an advisory lock, meaning that the file could be accessed by other programs that don't hold the lock.

It is unspecified whether this function succeeds if the file descriptor is not opened for writing. It is unspecified how exclusive locks interact with locks acquired by non-WASI programs.

This function returns error-code::would-block if the lock cannot be acquired.

Not all filesystems support locking; on filesystems which don't support locking, this function returns error-code::unsupported.

Note: This is similar to flock(fd, LOCK_EX | LOCK_NB) in Unix.

Params
Return values

unlock: func

Release a shared or exclusive lock on an open file.

Note: This is similar to flock(fd, LOCK_UN) in Unix.

Params
Return values

drop-descriptor: func

Dispose of the specified descriptor, after which it may no longer be used.

Params

read-directory-entry: func

Read a single directory entry from a directory-entry-stream.

Params
Return values

drop-directory-entry-stream: func

Dispose of the specified directory-entry-stream, after which it may no longer be used.

Params

Import interface wasi:filesystem/preopens

Types

type descriptor

descriptor

----

Functions

get-directories: func

Return the set of preopened directories, and their path.

Return values