Debian Codegraph @

wasi/p3/wit/deps/wasi-filesystem-0.3.0-rc-2026-01-06/package.wit

raw
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 }