| 1 |
package wasi:[email protected]; |
| 2 |
|
| 3 |
/// WASI filesystem is a filesystem API primarily intended to let users run WASI |
| 4 |
/// programs that access their files on their existing filesystems, without |
| 5 |
/// significant overhead. |
| 6 |
/// |
| 7 |
/// It is intended to be roughly portable between Unix-family platforms and |
| 8 |
/// Windows, though it does not hide many of the major differences. |
| 9 |
/// |
| 10 |
/// Paths are passed as interface-type `string`s, meaning they must consist of |
| 11 |
/// a sequence of Unicode Scalar Values (USVs). Some filesystems may contain |
| 12 |
/// paths which are not accessible by this API. |
| 13 |
/// |
| 14 |
/// The directory separator in WASI is always the forward-slash (`/`). |
| 15 |
/// |
| 16 |
/// All paths in WASI are relative paths, and are interpreted relative to a |
| 17 |
/// `descriptor` referring to a base directory. If a `path` argument to any WASI |
| 18 |
/// function starts with `/`, or if any step of resolving a `path`, including |
| 19 |
/// `..` and symbolic link steps, reaches a directory outside of the base |
| 20 |
/// directory, or reaches a symlink to an absolute or rooted path in the |
| 21 |
/// underlying filesystem, the function fails with `error-code::not-permitted`. |
| 22 |
/// |
| 23 |
/// For more information about WASI path resolution and sandboxing, see |
| 24 |
/// [WASI filesystem path resolution]. |
| 25 |
/// |
| 26 |
/// [WASI filesystem path resolution]: https://github.com/WebAssembly/wasi-filesystem/blob/main/path-resolution.md |
| 27 |
@since(version = 0.3.0-rc-2026-01-06) |
| 28 |
interface types { |
| 29 |
@since(version = 0.3.0-rc-2026-01-06) |
| 30 |
use wasi:clocks/[email protected].{instant}; |
| 31 |
|
| 32 |
/// File size or length of a region within a file. |
| 33 |
@since(version = 0.3.0-rc-2026-01-06) |
| 34 |
type filesize = u64; |
| 35 |
|
| 36 |
/// The type of a filesystem object referenced by a descriptor. |
| 37 |
/// |
| 38 |
/// Note: This was called `filetype` in earlier versions of WASI. |
| 39 |
@since(version = 0.3.0-rc-2026-01-06) |
| 40 |
enum descriptor-type { |
| 41 |
/// The type of the descriptor or file is unknown or is different from |
| 42 |
/// any of the other types specified. |
| 43 |
unknown, |
| 44 |
/// The descriptor refers to a block device inode. |
| 45 |
block-device, |
| 46 |
/// The descriptor refers to a character device inode. |
| 47 |
character-device, |
| 48 |
/// The descriptor refers to a directory inode. |
| 49 |
directory, |
| 50 |
/// The descriptor refers to a named pipe. |
| 51 |
fifo, |
| 52 |
/// The file refers to a symbolic link inode. |
| 53 |
symbolic-link, |
| 54 |
/// The descriptor refers to a regular file inode. |
| 55 |
regular-file, |
| 56 |
/// The descriptor refers to a socket. |
| 57 |
socket, |
| 58 |
} |
| 59 |
|
| 60 |
/// Descriptor flags. |
| 61 |
/// |
| 62 |
/// Note: This was called `fdflags` in earlier versions of WASI. |
| 63 |
@since(version = 0.3.0-rc-2026-01-06) |
| 64 |
flags descriptor-flags { |
| 65 |
/// Read mode: Data can be read. |
| 66 |
read, |
| 67 |
/// Write mode: Data can be written to. |
| 68 |
write, |
| 69 |
/// Request that writes be performed according to synchronized I/O file |
| 70 |
/// integrity completion. The data stored in the file and the file's |
| 71 |
/// metadata are synchronized. This is similar to `O_SYNC` in POSIX. |
| 72 |
/// |
| 73 |
/// The precise semantics of this operation have not yet been defined for |
| 74 |
/// WASI. At this time, it should be interpreted as a request, and not a |
| 75 |
/// requirement. |
| 76 |
file-integrity-sync, |
| 77 |
/// Request that writes be performed according to synchronized I/O data |
| 78 |
/// integrity completion. Only the data stored in the file is |
| 79 |
/// synchronized. This is similar to `O_DSYNC` in POSIX. |
| 80 |
/// |
| 81 |
/// The precise semantics of this operation have not yet been defined for |
| 82 |
/// WASI. At this time, it should be interpreted as a request, and not a |
| 83 |
/// requirement. |
| 84 |
data-integrity-sync, |
| 85 |
/// Requests that reads be performed at the same level of integrity |
| 86 |
/// requested for writes. This is similar to `O_RSYNC` in POSIX. |
| 87 |
/// |
| 88 |
/// The precise semantics of this operation have not yet been defined for |
| 89 |
/// WASI. At this time, it should be interpreted as a request, and not a |
| 90 |
/// requirement. |
| 91 |
requested-write-sync, |
| 92 |
/// Mutating directories mode: Directory contents may be mutated. |
| 93 |
/// |
| 94 |
/// When this flag is unset on a descriptor, operations using the |
| 95 |
/// descriptor which would create, rename, delete, modify the data or |
| 96 |
/// metadata of filesystem objects, or obtain another handle which |
| 97 |
/// would permit any of those, shall fail with `error-code::read-only` if |
| 98 |
/// they would otherwise succeed. |
| 99 |
/// |
| 100 |
/// This may only be set on directories. |
| 101 |
mutate-directory, |
| 102 |
} |
| 103 |
|
| 104 |
/// Flags determining the method of how paths are resolved. |
| 105 |
@since(version = 0.3.0-rc-2026-01-06) |
| 106 |
flags path-flags { |
| 107 |
/// As long as the resolved path corresponds to a symbolic link, it is |
| 108 |
/// expanded. |
| 109 |
symlink-follow, |
| 110 |
} |
| 111 |
|
| 112 |
/// Open flags used by `open-at`. |
| 113 |
@since(version = 0.3.0-rc-2026-01-06) |
| 114 |
flags open-flags { |
| 115 |
/// Create file if it does not exist, similar to `O_CREAT` in POSIX. |
| 116 |
create, |
| 117 |
/// Fail if not a directory, similar to `O_DIRECTORY` in POSIX. |
| 118 |
directory, |
| 119 |
/// Fail if file already exists, similar to `O_EXCL` in POSIX. |
| 120 |
exclusive, |
| 121 |
/// Truncate file to size 0, similar to `O_TRUNC` in POSIX. |
| 122 |
truncate, |
| 123 |
} |
| 124 |
|
| 125 |
/// Number of hard links to an inode. |
| 126 |
@since(version = 0.3.0-rc-2026-01-06) |
| 127 |
type link-count = u64; |
| 128 |
|
| 129 |
/// File attributes. |
| 130 |
/// |
| 131 |
/// Note: This was called `filestat` in earlier versions of WASI. |
| 132 |
@since(version = 0.3.0-rc-2026-01-06) |
| 133 |
record descriptor-stat { |
| 134 |
/// File type. |
| 135 |
%type: descriptor-type, |
| 136 |
/// Number of hard links to the file. |
| 137 |
link-count: link-count, |
| 138 |
/// For regular files, the file size in bytes. For symbolic links, the |
| 139 |
/// length in bytes of the pathname contained in the symbolic link. |
| 140 |
size: filesize, |
| 141 |
/// Last data access timestamp. |
| 142 |
/// |
| 143 |
/// If the `option` is none, the platform doesn't maintain an access |
| 144 |
/// timestamp for this file. |
| 145 |
data-access-timestamp: option<instant>, |
| 146 |
/// Last data modification timestamp. |
| 147 |
/// |
| 148 |
/// If the `option` is none, the platform doesn't maintain a |
| 149 |
/// modification timestamp for this file. |
| 150 |
data-modification-timestamp: option<instant>, |
| 151 |
/// Last file status-change timestamp. |
| 152 |
/// |
| 153 |
/// If the `option` is none, the platform doesn't maintain a |
| 154 |
/// status-change timestamp for this file. |
| 155 |
status-change-timestamp: option<instant>, |
| 156 |
} |
| 157 |
|
| 158 |
/// When setting a timestamp, this gives the value to set it to. |
| 159 |
@since(version = 0.3.0-rc-2026-01-06) |
| 160 |
variant new-timestamp { |
| 161 |
/// Leave the timestamp set to its previous value. |
| 162 |
no-change, |
| 163 |
/// Set the timestamp to the current time of the system clock associated |
| 164 |
/// with the filesystem. |
| 165 |
now, |
| 166 |
/// Set the timestamp to the given value. |
| 167 |
timestamp(instant), |
| 168 |
} |
| 169 |
|
| 170 |
/// A directory entry. |
| 171 |
record directory-entry { |
| 172 |
/// The type of the file referred to by this directory entry. |
| 173 |
%type: descriptor-type, |
| 174 |
/// The name of the object. |
| 175 |
name: string, |
| 176 |
} |
| 177 |
|
| 178 |
/// Error codes returned by functions, similar to `errno` in POSIX. |
| 179 |
/// Not all of these error codes are returned by the functions provided by this |
| 180 |
/// API; some are used in higher-level library layers, and others are provided |
| 181 |
/// merely for alignment with POSIX. |
| 182 |
enum error-code { |
| 183 |
/// Permission denied, similar to `EACCES` in POSIX. |
| 184 |
access, |
| 185 |
/// Connection already in progress, similar to `EALREADY` in POSIX. |
| 186 |
already, |
| 187 |
/// Bad descriptor, similar to `EBADF` in POSIX. |
| 188 |
bad-descriptor, |
| 189 |
/// Device or resource busy, similar to `EBUSY` in POSIX. |
| 190 |
busy, |
| 191 |
/// Resource deadlock would occur, similar to `EDEADLK` in POSIX. |
| 192 |
deadlock, |
| 193 |
/// Storage quota exceeded, similar to `EDQUOT` in POSIX. |
| 194 |
quota, |
| 195 |
/// File exists, similar to `EEXIST` in POSIX. |
| 196 |
exist, |
| 197 |
/// File too large, similar to `EFBIG` in POSIX. |
| 198 |
file-too-large, |
| 199 |
/// Illegal byte sequence, similar to `EILSEQ` in POSIX. |
| 200 |
illegal-byte-sequence, |
| 201 |
/// Operation in progress, similar to `EINPROGRESS` in POSIX. |
| 202 |
in-progress, |
| 203 |
/// Interrupted function, similar to `EINTR` in POSIX. |
| 204 |
interrupted, |
| 205 |
/// Invalid argument, similar to `EINVAL` in POSIX. |
| 206 |
invalid, |
| 207 |
/// I/O error, similar to `EIO` in POSIX. |
| 208 |
io, |
| 209 |
/// Is a directory, similar to `EISDIR` in POSIX. |
| 210 |
is-directory, |
| 211 |
/// Too many levels of symbolic links, similar to `ELOOP` in POSIX. |
| 212 |
loop, |
| 213 |
/// Too many links, similar to `EMLINK` in POSIX. |
| 214 |
too-many-links, |
| 215 |
/// Message too large, similar to `EMSGSIZE` in POSIX. |
| 216 |
message-size, |
| 217 |
/// Filename too long, similar to `ENAMETOOLONG` in POSIX. |
| 218 |
name-too-long, |
| 219 |
/// No such device, similar to `ENODEV` in POSIX. |
| 220 |
no-device, |
| 221 |
/// No such file or directory, similar to `ENOENT` in POSIX. |
| 222 |
no-entry, |
| 223 |
/// No locks available, similar to `ENOLCK` in POSIX. |
| 224 |
no-lock, |
| 225 |
/// Not enough space, similar to `ENOMEM` in POSIX. |
| 226 |
insufficient-memory, |
| 227 |
/// No space left on device, similar to `ENOSPC` in POSIX. |
| 228 |
insufficient-space, |
| 229 |
/// Not a directory or a symbolic link to a directory, similar to `ENOTDIR` in POSIX. |
| 230 |
not-directory, |
| 231 |
/// Directory not empty, similar to `ENOTEMPTY` in POSIX. |
| 232 |
not-empty, |
| 233 |
/// State not recoverable, similar to `ENOTRECOVERABLE` in POSIX. |
| 234 |
not-recoverable, |
| 235 |
/// Not supported, similar to `ENOTSUP` and `ENOSYS` in POSIX. |
| 236 |
unsupported, |
| 237 |
/// Inappropriate I/O control operation, similar to `ENOTTY` in POSIX. |
| 238 |
no-tty, |
| 239 |
/// No such device or address, similar to `ENXIO` in POSIX. |
| 240 |
no-such-device, |
| 241 |
/// Value too large to be stored in data type, similar to `EOVERFLOW` in POSIX. |
| 242 |
overflow, |
| 243 |
/// Operation not permitted, similar to `EPERM` in POSIX. |
| 244 |
not-permitted, |
| 245 |
/// Broken pipe, similar to `EPIPE` in POSIX. |
| 246 |
pipe, |
| 247 |
/// Read-only file system, similar to `EROFS` in POSIX. |
| 248 |
read-only, |
| 249 |
/// Invalid seek, similar to `ESPIPE` in POSIX. |
| 250 |
invalid-seek, |
| 251 |
/// Text file busy, similar to `ETXTBSY` in POSIX. |
| 252 |
text-file-busy, |
| 253 |
/// Cross-device link, similar to `EXDEV` in POSIX. |
| 254 |
cross-device, |
| 255 |
} |
| 256 |
|
| 257 |
/// File or memory access pattern advisory information. |
| 258 |
@since(version = 0.3.0-rc-2026-01-06) |
| 259 |
enum advice { |
| 260 |
/// The application has no advice to give on its behavior with respect |
| 261 |
/// to the specified data. |
| 262 |
normal, |
| 263 |
/// The application expects to access the specified data sequentially |
| 264 |
/// from lower offsets to higher offsets. |
| 265 |
sequential, |
| 266 |
/// The application expects to access the specified data in a random |
| 267 |
/// order. |
| 268 |
random, |
| 269 |
/// The application expects to access the specified data in the near |
| 270 |
/// future. |
| 271 |
will-need, |
| 272 |
/// The application expects that it will not access the specified data |
| 273 |
/// in the near future. |
| 274 |
dont-need, |
| 275 |
/// The application expects to access the specified data once and then |
| 276 |
/// not reuse it thereafter. |
| 277 |
no-reuse, |
| 278 |
} |
| 279 |
|
| 280 |
/// A 128-bit hash value, split into parts because wasm doesn't have a |
| 281 |
/// 128-bit integer type. |
| 282 |
@since(version = 0.3.0-rc-2026-01-06) |
| 283 |
record metadata-hash-value { |
| 284 |
/// 64 bits of a 128-bit hash value. |
| 285 |
lower: u64, |
| 286 |
/// Another 64 bits of a 128-bit hash value. |
| 287 |
upper: u64, |
| 288 |
} |
| 289 |
|
| 290 |
/// A descriptor is a reference to a filesystem object, which may be a file, |
| 291 |
/// directory, named pipe, special file, or other object on which filesystem |
| 292 |
/// calls may be made. |
| 293 |
@since(version = 0.3.0-rc-2026-01-06) |
| 294 |
resource descriptor { |
| 295 |
/// Return a stream for reading from a file. |
| 296 |
/// |
| 297 |
/// Multiple read, write, and append streams may be active on the same open |
| 298 |
/// file and they do not interfere with each other. |
| 299 |
/// |
| 300 |
/// This function returns a `stream` which provides the data received from the |
| 301 |
/// file, and a `future` providing additional error information in case an |
| 302 |
/// error is encountered. |
| 303 |
/// |
| 304 |
/// If no error is encountered, `stream.read` on the `stream` will return |
| 305 |
/// `read-status::closed` with no `error-context` and the future resolves to |
| 306 |
/// the value `ok`. If an error is encountered, `stream.read` on the |
| 307 |
/// `stream` returns `read-status::closed` with an `error-context` and the future |
| 308 |
/// resolves to `err` with an `error-code`. |
| 309 |
/// |
| 310 |
/// Note: This is similar to `pread` in POSIX. |
| 311 |
@since(version = 0.3.0-rc-2026-01-06) |
| 312 |
read-via-stream: func(offset: filesize) -> tuple<stream<u8>, future<result<_, error-code>>>; |
| 313 |
/// Return a stream for writing to a file, if available. |
| 314 |
/// |
| 315 |
/// May fail with an error-code describing why the file cannot be written. |
| 316 |
/// |
| 317 |
/// It is valid to write past the end of a file; the file is extended to the |
| 318 |
/// extent of the write, with bytes between the previous end and the start of |
| 319 |
/// the write set to zero. |
| 320 |
/// |
| 321 |
/// This function returns once either full contents of the stream are |
| 322 |
/// written or an error is encountered. |
| 323 |
/// |
| 324 |
/// Note: This is similar to `pwrite` in POSIX. |
| 325 |
@since(version = 0.3.0-rc-2026-01-06) |
| 326 |
write-via-stream: async func(data: stream<u8>, offset: filesize) -> result<_, error-code>; |
| 327 |
/// Return a stream for appending to a file, if available. |
| 328 |
/// |
| 329 |
/// May fail with an error-code describing why the file cannot be appended. |
| 330 |
/// |
| 331 |
/// This function returns once either full contents of the stream are |
| 332 |
/// written or an error is encountered. |
| 333 |
/// |
| 334 |
/// Note: This is similar to `write` with `O_APPEND` in POSIX. |
| 335 |
@since(version = 0.3.0-rc-2026-01-06) |
| 336 |
append-via-stream: async func(data: stream<u8>) -> result<_, error-code>; |
| 337 |
/// Provide file advisory information on a descriptor. |
| 338 |
/// |
| 339 |
/// This is similar to `posix_fadvise` in POSIX. |
| 340 |
@since(version = 0.3.0-rc-2026-01-06) |
| 341 |
advise: async func(offset: filesize, length: filesize, advice: advice) -> result<_, error-code>; |
| 342 |
/// Synchronize the data of a file to disk. |
| 343 |
/// |
| 344 |
/// This function succeeds with no effect if the file descriptor is not |
| 345 |
/// opened for writing. |
| 346 |
/// |
| 347 |
/// Note: This is similar to `fdatasync` in POSIX. |
| 348 |
@since(version = 0.3.0-rc-2026-01-06) |
| 349 |
sync-data: async func() -> result<_, error-code>; |
| 350 |
/// Get flags associated with a descriptor. |
| 351 |
/// |
| 352 |
/// Note: This returns similar flags to `fcntl(fd, F_GETFL)` in POSIX. |
| 353 |
/// |
| 354 |
/// Note: This returns the value that was the `fs_flags` value returned |
| 355 |
/// from `fdstat_get` in earlier versions of WASI. |
| 356 |
@since(version = 0.3.0-rc-2026-01-06) |
| 357 |
get-flags: async func() -> result<descriptor-flags, error-code>; |
| 358 |
/// Get the dynamic type of a descriptor. |
| 359 |
/// |
| 360 |
/// Note: This returns the same value as the `type` field of the `fd-stat` |
| 361 |
/// returned by `stat`, `stat-at` and similar. |
| 362 |
/// |
| 363 |
/// Note: This returns similar flags to the `st_mode & S_IFMT` value provided |
| 364 |
/// by `fstat` in POSIX. |
| 365 |
/// |
| 366 |
/// Note: This returns the value that was the `fs_filetype` value returned |
| 367 |
/// from `fdstat_get` in earlier versions of WASI. |
| 368 |
@since(version = 0.3.0-rc-2026-01-06) |
| 369 |
get-type: async func() -> result<descriptor-type, error-code>; |
| 370 |
/// Adjust the size of an open file. If this increases the file's size, the |
| 371 |
/// extra bytes are filled with zeros. |
| 372 |
/// |
| 373 |
/// Note: This was called `fd_filestat_set_size` in earlier versions of WASI. |
| 374 |
@since(version = 0.3.0-rc-2026-01-06) |
| 375 |
set-size: async func(size: filesize) -> result<_, error-code>; |
| 376 |
/// Adjust the timestamps of an open file or directory. |
| 377 |
/// |
| 378 |
/// Note: This is similar to `futimens` in POSIX. |
| 379 |
/// |
| 380 |
/// Note: This was called `fd_filestat_set_times` in earlier versions of WASI. |
| 381 |
@since(version = 0.3.0-rc-2026-01-06) |
| 382 |
set-times: async func(data-access-timestamp: new-timestamp, data-modification-timestamp: new-timestamp) -> result<_, error-code>; |
| 383 |
/// Read directory entries from a directory. |
| 384 |
/// |
| 385 |
/// On filesystems where directories contain entries referring to themselves |
| 386 |
/// and their parents, often named `.` and `..` respectively, these entries |
| 387 |
/// are omitted. |
| 388 |
/// |
| 389 |
/// This always returns a new stream which starts at the beginning of the |
| 390 |
/// directory. Multiple streams may be active on the same directory, and they |
| 391 |
/// do not interfere with each other. |
| 392 |
/// |
| 393 |
/// This function returns a future, which will resolve to an error code if |
| 394 |
/// reading full contents of the directory fails. |
| 395 |
@since(version = 0.3.0-rc-2026-01-06) |
| 396 |
read-directory: async func() -> tuple<stream<directory-entry>, future<result<_, error-code>>>; |
| 397 |
/// Synchronize the data and metadata of a file to disk. |
| 398 |
/// |
| 399 |
/// This function succeeds with no effect if the file descriptor is not |
| 400 |
/// opened for writing. |
| 401 |
/// |
| 402 |
/// Note: This is similar to `fsync` in POSIX. |
| 403 |
@since(version = 0.3.0-rc-2026-01-06) |
| 404 |
sync: async func() -> result<_, error-code>; |
| 405 |
/// Create a directory. |
| 406 |
/// |
| 407 |
/// Note: This is similar to `mkdirat` in POSIX. |
| 408 |
@since(version = 0.3.0-rc-2026-01-06) |
| 409 |
create-directory-at: async func(path: string) -> result<_, error-code>; |
| 410 |
/// Return the attributes of an open file or directory. |
| 411 |
/// |
| 412 |
/// Note: This is similar to `fstat` in POSIX, except that it does not return |
| 413 |
/// device and inode information. For testing whether two descriptors refer to |
| 414 |
/// the same underlying filesystem object, use `is-same-object`. To obtain |
| 415 |
/// additional data that can be used do determine whether a file has been |
| 416 |
/// modified, use `metadata-hash`. |
| 417 |
/// |
| 418 |
/// Note: This was called `fd_filestat_get` in earlier versions of WASI. |
| 419 |
@since(version = 0.3.0-rc-2026-01-06) |
| 420 |
stat: async func() -> result<descriptor-stat, error-code>; |
| 421 |
/// Return the attributes of a file or directory. |
| 422 |
/// |
| 423 |
/// Note: This is similar to `fstatat` in POSIX, except that it does not |
| 424 |
/// return device and inode information. See the `stat` description for a |
| 425 |
/// discussion of alternatives. |
| 426 |
/// |
| 427 |
/// Note: This was called `path_filestat_get` in earlier versions of WASI. |
| 428 |
@since(version = 0.3.0-rc-2026-01-06) |
| 429 |
stat-at: async func(path-flags: path-flags, path: string) -> result<descriptor-stat, error-code>; |
| 430 |
/// Adjust the timestamps of a file or directory. |
| 431 |
/// |
| 432 |
/// Note: This is similar to `utimensat` in POSIX. |
| 433 |
/// |
| 434 |
/// Note: This was called `path_filestat_set_times` in earlier versions of |
| 435 |
/// WASI. |
| 436 |
@since(version = 0.3.0-rc-2026-01-06) |
| 437 |
set-times-at: async func(path-flags: path-flags, path: string, data-access-timestamp: new-timestamp, data-modification-timestamp: new-timestamp) -> result<_, error-code>; |
| 438 |
/// Create a hard link. |
| 439 |
/// |
| 440 |
/// Fails with `error-code::no-entry` if the old path does not exist, |
| 441 |
/// with `error-code::exist` if the new path already exists, and |
| 442 |
/// `error-code::not-permitted` if the old path is not a file. |
| 443 |
/// |
| 444 |
/// Note: This is similar to `linkat` in POSIX. |
| 445 |
@since(version = 0.3.0-rc-2026-01-06) |
| 446 |
link-at: async func(old-path-flags: path-flags, old-path: string, new-descriptor: borrow<descriptor>, new-path: string) -> result<_, error-code>; |
| 447 |
/// Open a file or directory. |
| 448 |
/// |
| 449 |
/// If `flags` contains `descriptor-flags::mutate-directory`, and the base |
| 450 |
/// descriptor doesn't have `descriptor-flags::mutate-directory` set, |
| 451 |
/// `open-at` fails with `error-code::read-only`. |
| 452 |
/// |
| 453 |
/// If `flags` contains `write` or `mutate-directory`, or `open-flags` |
| 454 |
/// contains `truncate` or `create`, and the base descriptor doesn't have |
| 455 |
/// `descriptor-flags::mutate-directory` set, `open-at` fails with |
| 456 |
/// `error-code::read-only`. |
| 457 |
/// |
| 458 |
/// Note: This is similar to `openat` in POSIX. |
| 459 |
@since(version = 0.3.0-rc-2026-01-06) |
| 460 |
open-at: async func(path-flags: path-flags, path: string, open-flags: open-flags, %flags: descriptor-flags) -> result<descriptor, error-code>; |
| 461 |
/// Read the contents of a symbolic link. |
| 462 |
/// |
| 463 |
/// If the contents contain an absolute or rooted path in the underlying |
| 464 |
/// filesystem, this function fails with `error-code::not-permitted`. |
| 465 |
/// |
| 466 |
/// Note: This is similar to `readlinkat` in POSIX. |
| 467 |
@since(version = 0.3.0-rc-2026-01-06) |
| 468 |
readlink-at: async func(path: string) -> result<string, error-code>; |
| 469 |
/// Remove a directory. |
| 470 |
/// |
| 471 |
/// Return `error-code::not-empty` if the directory is not empty. |
| 472 |
/// |
| 473 |
/// Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX. |
| 474 |
@since(version = 0.3.0-rc-2026-01-06) |
| 475 |
remove-directory-at: async func(path: string) -> result<_, error-code>; |
| 476 |
/// Rename a filesystem object. |
| 477 |
/// |
| 478 |
/// Note: This is similar to `renameat` in POSIX. |
| 479 |
@since(version = 0.3.0-rc-2026-01-06) |
| 480 |
rename-at: async func(old-path: string, new-descriptor: borrow<descriptor>, new-path: string) -> result<_, error-code>; |
| 481 |
/// Create a symbolic link (also known as a "symlink"). |
| 482 |
/// |
| 483 |
/// If `old-path` starts with `/`, the function fails with |
| 484 |
/// `error-code::not-permitted`. |
| 485 |
/// |
| 486 |
/// Note: This is similar to `symlinkat` in POSIX. |
| 487 |
@since(version = 0.3.0-rc-2026-01-06) |
| 488 |
symlink-at: async func(old-path: string, new-path: string) -> result<_, error-code>; |
| 489 |
/// Unlink a filesystem object that is not a directory. |
| 490 |
/// |
| 491 |
/// Return `error-code::is-directory` if the path refers to a directory. |
| 492 |
/// Note: This is similar to `unlinkat(fd, path, 0)` in POSIX. |
| 493 |
@since(version = 0.3.0-rc-2026-01-06) |
| 494 |
unlink-file-at: async func(path: string) -> result<_, error-code>; |
| 495 |
/// Test whether two descriptors refer to the same filesystem object. |
| 496 |
/// |
| 497 |
/// In POSIX, this corresponds to testing whether the two descriptors have the |
| 498 |
/// same device (`st_dev`) and inode (`st_ino` or `d_ino`) numbers. |
| 499 |
/// wasi-filesystem does not expose device and inode numbers, so this function |
| 500 |
/// may be used instead. |
| 501 |
@since(version = 0.3.0-rc-2026-01-06) |
| 502 |
is-same-object: async func(other: borrow<descriptor>) -> bool; |
| 503 |
/// Return a hash of the metadata associated with a filesystem object referred |
| 504 |
/// to by a descriptor. |
| 505 |
/// |
| 506 |
/// This returns a hash of the last-modification timestamp and file size, and |
| 507 |
/// may also include the inode number, device number, birth timestamp, and |
| 508 |
/// other metadata fields that may change when the file is modified or |
| 509 |
/// replaced. It may also include a secret value chosen by the |
| 510 |
/// implementation and not otherwise exposed. |
| 511 |
/// |
| 512 |
/// Implementations are encouraged to provide the following properties: |
| 513 |
/// |
| 514 |
/// - If the file is not modified or replaced, the computed hash value should |
| 515 |
/// usually not change. |
| 516 |
/// - If the object is modified or replaced, the computed hash value should |
| 517 |
/// usually change. |
| 518 |
/// - The inputs to the hash should not be easily computable from the |
| 519 |
/// computed hash. |
| 520 |
/// |
| 521 |
/// However, none of these is required. |
| 522 |
@since(version = 0.3.0-rc-2026-01-06) |
| 523 |
metadata-hash: async func() -> result<metadata-hash-value, error-code>; |
| 524 |
/// Return a hash of the metadata associated with a filesystem object referred |
| 525 |
/// to by a directory descriptor and a relative path. |
| 526 |
/// |
| 527 |
/// This performs the same hash computation as `metadata-hash`. |
| 528 |
@since(version = 0.3.0-rc-2026-01-06) |
| 529 |
metadata-hash-at: async func(path-flags: path-flags, path: string) -> result<metadata-hash-value, error-code>; |
| 530 |
} |
| 531 |
} |
| 532 |
|
| 533 |
@since(version = 0.3.0-rc-2026-01-06) |
| 534 |
interface preopens { |
| 535 |
@since(version = 0.3.0-rc-2026-01-06) |
| 536 |
use types.{descriptor}; |
| 537 |
|
| 538 |
/// Return the set of preopened directories, and their paths. |
| 539 |
@since(version = 0.3.0-rc-2026-01-06) |
| 540 |
get-directories: func() -> list<tuple<descriptor, string>>; |
| 541 |
} |
| 542 |
|
| 543 |
@since(version = 0.3.0-rc-2026-01-06) |
| 544 |
world imports { |
| 545 |
@since(version = 0.3.0-rc-2026-01-06) |
| 546 |
import wasi:clocks/[email protected]; |
| 547 |
@since(version = 0.3.0-rc-2026-01-06) |
| 548 |
import wasi:clocks/[email protected]; |
| 549 |
@since(version = 0.3.0-rc-2026-01-06) |
| 550 |
import types; |
| 551 |
@since(version = 0.3.0-rc-2026-01-06) |
| 552 |
import preopens; |
| 553 |
} |