From 58e3e5d957b7b1b2b166bdd9452778387427116a Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Thu, 20 Jul 2023 10:24:41 -0700 Subject: [PATCH] Remove the device and inode numbers from the API. As discussed [here], remove the fields which correspond to `st_dev`, `st_ino`, and `d_ino` in POSIX from the stat and directory entry structs. - Device numbers assume the existence of a global device number space, which creates implicit relationships between otherwise unrelated components. - Not all filesystem implementations have these numbers. And some that do have these numbers require extra implementation cost to retrieve them. - These numbers leak potentially sensitive or identifying information from the underlying filesystem implementation. In their place, provide some functions, `is-same-object`, `metadata-hash`, and `metadata-hash-at`, for explicitly testing whether two handles are the same file or have the same metadata, respectively. This doesn't cover all possible use cases for device and inode numbers, but we can add more functions as need arises. [here]: #65 (comment) --- example-world.md | 486 +++++++++++++++++++++++++---------------------- 1 file changed, 258 insertions(+), 228 deletions(-) diff --git a/example-world.md b/example-world.md index 9920763..a45e65d 100644 --- a/example-world.md +++ b/example-world.md @@ -71,21 +71,6 @@ when it does, they are expected to subsume this API.

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 @@ -101,6 +86,21 @@ 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 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.

Functions

read: func

@@ -377,7 +377,108 @@ underlying filesystem, the function fails with `type datetime` [`datetime`](#datetime)

-#### `flags path-flags` +#### `type filesize` +`u64` +

File size or length of a region within a file. +

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
+ +

flags descriptor-flags

+

Descriptor flags.

+

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

+
Flags members
+ +

flags path-flags

Flags determining the method of how paths are resolved.

Flags members
+

variant access-type

+

Access type used by access-at.

+
Variant Cases
+

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

record descriptor-stat

+

File attributes.

+

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

+
Record Fields
+ +

variant new-timestamp

+

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

+
Variant Cases
+ +

record directory-entry

+

A directory entry.

+
Record Fields
+

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 @@ -592,197 +762,6 @@ merely for alignment with POSIX.

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

record directory-entry

-

A directory entry.

-
Record Fields
- -

flags descriptor-flags

-

Descriptor flags.

-

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

-
Flags members
- -

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

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
@@ -818,19 +797,16 @@ in the near future. not reuse it thereafter. -

variant access-type

-

Access type used by access-at.

-
Variant Cases
- +

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.

+

type directory-entry-stream

+

u32

+

A stream of directory entries. +

This represents a stream of dir-entry.

Functions

read-via-stream: func

@@ -1051,7 +1027,11 @@ opened for writing.

stat: func

Return the attributes of an open file or directory.

-

Note: This is similar to fstat in POSIX.

+

Note: This is similar to fstat in POSIX, except that it does not return +device and inode information. For testing whether two descriptors refer to +the same underlying filesystem object, use is-same-object. To obtain +additional data that can be used do determine whether a file has been +modified, use metadata-hash.

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

Params

stat-at: func

Return the attributes of a file or directory.

-

Note: This is similar to fstatat in POSIX.

+

Note: This is similar to fstatat in POSIX, except that it does not +return device and inode information. See the stat description for a +discussion of alternatives.

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

Params