From d722b354db2c29c4fd067f697c921da2e2db8e7e Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Tue, 9 Apr 2019 12:19:18 -0700 Subject: [PATCH] Miscellaneous tidying in the API docs. - Don't include an extra "*" in type of Output arguments. - Fix the summary of environ_sizes_get. - Put fs_rights_base and fs_rights_inherinting arguments on separate lines. - Sort fd_prestat_dirname alphabetically before fd_prestat_get. --- docs/WASI-api.md | 75 +++++++++++++++++++++++++++--------------------- 1 file changed, 43 insertions(+), 32 deletions(-) diff --git a/docs/WASI-api.md b/docs/WASI-api.md index 96f800a8fa..6cf2886e28 100644 --- a/docs/WASI-api.md +++ b/docs/WASI-api.md @@ -80,8 +80,8 @@ This is also a work in progress, and the API here is still evolving. - [`__wasi_fd_filestat_set_size()`](#fd_filestat_set_size) - [`__wasi_fd_filestat_set_times()`](#fd_filestat_set_times) - [`__wasi_fd_pread()`](#fd_pread) -- [`__wasi_fd_prestat_get()`](#fd_prestat_get) - [`__wasi_fd_prestat_dir_name()`](#fd_prestat_dir_name) +- [`__wasi_fd_prestat_get()`](#fd_prestat_get) - [`__wasi_fd_pwrite()`](#fd_pwrite) - [`__wasi_fd_read()`](#fd_read) - [`__wasi_fd_readdir()`](#fd_readdir) @@ -131,11 +131,11 @@ Return command-line argument data sizes. Outputs: -- size\_t \*argc +- size\_t argc The number of arguments. -- size\_t \*argv\_buf\_size +- size\_t argv\_buf\_size The size of the argument string data. @@ -202,15 +202,15 @@ Inputs: ### `__wasi_environ_sizes_get()` -Return command-line argument data sizes. +Return environment variable data sizes. Outputs: -- size\_t \*environ\_count +- size\_t environ\_count The number of environment variables. -- size\_t \*environ\_buf\_size +- size\_t environ\_buf\_size The size of the environment variable string data. @@ -313,8 +313,7 @@ Inputs: - [\_\_wasi\_fdflags\_t](#fdflags) flags - The desired values of the file descriptor - flags. + The desired values of the file descriptor flags. ### `__wasi_fd_fdstat_set_rights()` @@ -330,9 +329,13 @@ Inputs: The file descriptor to operate on. -- [\_\_wasi\_rights\_t](#rights) fs\_rights\_base and [\_\_wasi\_rights\_t](#rights) fs\_rights\_inheriting +- [\_\_wasi\_rights\_t](#rights) fs\_rights\_base - The desired rights of the file descriptor. + The desired base rights of the file descriptor. + +- [\_\_wasi\_rights\_t](#rights) fs\_rights\_inheriting + + The desired inheriting rights of the file descriptor. ### `__wasi_fd_filestat_get()` @@ -417,20 +420,6 @@ Outputs: The number of bytes read. -### `__wasi_fd_prestat_get()` - -Return a description of the given preopened file descriptor. - -Inputs: - -- [\_\_wasi\_fd\_t](#fd) fd - - The file descriptor about which to retrieve information. - -- [\_\_wasi\_prestat\_t](#prestat) \*buf - - The buffer where the description is stored. - ### `__wasi_fd_prestat_dir_name()` Return a description of the given preopened file descriptor. @@ -445,6 +434,20 @@ Inputs: A buffer into which to write the preopened directory name. +### `__wasi_fd_prestat_get()` + +Return a description of the given preopened file descriptor. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor about which to retrieve information. + +- [\_\_wasi\_prestat\_t](#prestat) \*buf + + The buffer where the description is stored. + ### `__wasi_fd_pwrite()` Write to a file descriptor, without using and updating the @@ -677,8 +680,7 @@ Inputs: - [\_\_wasi\_filestat\_t](#filestat) \*buf - The buffer where the file's attributes are - stored. + The buffer where the file's attributes are stored. ### `__wasi_path_filestat_set_times()` @@ -770,16 +772,25 @@ Inputs: The method by which to open the file. -- [\_\_wasi\_rights\_t](#rights) fs\_rights\_base and [\_\_wasi\_rights\_t](#rights) fs\_rights\_inheriting +- [\_\_wasi\_rights\_t](#rights) fs\_rights\_base - The initial rights of the newly created file descriptor. The + The initial base rights of the newly created file descriptor. The implementation is allowed to return a file descriptor with fewer rights than specified, if and only if those rights do not apply to the type of file being opened. The *base* rights are rights that will apply to operations using - the file descriptor itself, while the *inheriting* rights are - rights that apply to file descriptors derived from it. + the file descriptor itself. + +- [\_\_wasi\_rights\_t](#rights) fs\_rights\_inheriting + + The initial inheriting rights of the newly created file descriptor. The + implementation is allowed to return a file descriptor with fewer + rights than specified, if and only if those rights do not apply + to the type of file being opened. + + The *inheriting* rights are rights that will apply to file descriptors derived + from the file descriptor itself. - [\_\_wasi\_fdflags\_t](#fdflags) fs\_flags @@ -1020,7 +1031,7 @@ Inputs: - const [\_\_wasi\_ciovec\_t](#ciovec) \*si\_data and size\_t si\_data\_len - List of scatter/gather vectors to which to retrieve data + List of scatter/gather vectors to which to retrieve data. - [\_\_wasi\_siflags\_t](#siflags) si\_flags @@ -1657,7 +1668,7 @@ Used by [`__wasi_fd_seek()`](#fd_seek). Non-negative file size or length of a region within a file. -Used by [`__wasi_event_t`](#event), [`__wasi_filestat_t`](#filestat), [`__wasi_fd_pread()`](#fd_pread), [`__wasi_fd_pwrite()`](#fd_pwrite), [`__wasi_fd_seek()`](#fd_seek), [`__wasi_path_tell()`](#path_tell), [`__wasi_fd_advise()`](#fd_advise), [`__wasi_fd_allocate()`](#fd_allocate), and [`__wasi_fd_filestat_set_size()`](#fd_filestat_set_size). +Used by [`__wasi_event_t`](#event), [`__wasi_filestat_t`](#filestat), [`__wasi_fd_advise()`](#fd_advise), [`__wasi_fd_allocate()`](#fd_allocate), [`__wasi_fd_filestat_set_size()`](#fd_filestat_set_size), [`__wasi_fd_pread()`](#fd_pread), [`__wasi_fd_pwrite()`](#fd_pwrite), [`__wasi_fd_seek()`](#fd_seek), and [`__wasi_fd_tell()`](#fd_tell). ### `__wasi_filestat_t` (`struct`)