diff --git a/phases/ephemeral/witx/typenames.witx b/phases/ephemeral/witx/typenames.witx index 1a45be1fd..a614d8528 100644 --- a/phases/ephemeral/witx/typenames.witx +++ b/phases/ephemeral/witx/typenames.witx @@ -7,291 +7,291 @@ (typename $size_t u32) -;; Non-negative file size or length of a region within a file. +;;; Non-negative file size or length of a region within a file. (typename $filesize_t u64) -;; Timestamp in nanoseconds. +;;; Timestamp in nanoseconds. (typename $timestamp_t u64) -;; Identifiers for clocks. +;;; Identifiers for clocks. (typename $clockid_t (enum u32 - ;; The clock measuring real time. Time value zero corresponds with - ;; 1970-01-01T00:00:00Z. + ;;; The clock measuring real time. Time value zero corresponds with + ;;; 1970-01-01T00:00:00Z. $CLOCK_REALTIME - ;; The store-wide monotonic clock, which is defined as a clock measuring - ;; real time, whose value cannot be adjusted and which cannot have negative - ;; clock jumps. The epoch of this clock is undefined. The absolute time - ;; value of this clock therefore has no meaning. + ;;; The store-wide monotonic clock, which is defined as a clock measuring + ;;; real time, whose value cannot be adjusted and which cannot have negative + ;;; clock jumps. The epoch of this clock is undefined. The absolute time + ;;; value of this clock therefore has no meaning. $CLOCK_MONOTONIC - ;; The CPU-time clock associated with the current process. + ;;; The CPU-time clock associated with the current process. $CLOCK_PROCESS_CPUTIME_ID - ;; The CPU-time clock associated with the current thread. + ;;; The CPU-time clock associated with the current thread. $CLOCK_THREAD_CPUTIME_ID ) ) -;; Error codes returned by functions. -;; 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. +;;; Error codes returned by functions. +;;; 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. (typename $errno_t (enum u16 - ;; No error occurred. System call completed successfully. + ;;; No error occurred. System call completed successfully. $ESUCCESS - ;; Argument list too long. + ;;; Argument list too long. $E2BIG - ;; Permission denied. + ;;; Permission denied. $EACCES - ;; Address in use. + ;;; Address in use. $EADDRINUSE - ;; Address not available. + ;;; Address not available. $EADDRNOTAVAIL - ;; Address family not supported. + ;;; Address family not supported. $EAFNOSUPPORT - ;; Resource unavailable, or operation would block. + ;;; Resource unavailable, or operation would block. $EAGAIN - ;; Connection already in progress. + ;;; Connection already in progress. $EALREADY - ;; Bad file descriptor. + ;;; Bad file descriptor. $EBADF - ;; Bad message. + ;;; Bad message. $EBADMSG - ;; Device or resource busy. + ;;; Device or resource busy. $EBUSY - ;; Operation canceled. + ;;; Operation canceled. $ECANCELED - ;; No child processes. + ;;; No child processes. $ECHILD - ;; Connection aborted. + ;;; Connection aborted. $ECONNABORTED - ;; Connection refused. + ;;; Connection refused. $ECONNREFUSED - ;; Connection reset. + ;;; Connection reset. $ECONNRESET - ;; Resource deadlock would occur. + ;;; Resource deadlock would occur. $EDEADLK - ;; Destination address required. + ;;; Destination address required. $EDESTADDRREQ - ;; Mathematics argument out of domain of function. + ;;; Mathematics argument out of domain of function. $EDOM - ;; Reserved. + ;;; Reserved. $EDQUOT - ;; File exists. + ;;; File exists. $EEXIST - ;; Bad address. + ;;; Bad address. $EFAULT - ;; File too large. + ;;; File too large. $EFBIG - ;; Host is unreachable. + ;;; Host is unreachable. $EHOSTUNREACH - ;; Identifier removed. + ;;; Identifier removed. $EIDRM - ;; Illegal byte sequence. + ;;; Illegal byte sequence. $EILSEQ - ;; Operation in progress. + ;;; Operation in progress. $EINPROGRESS - ;; Interrupted function. + ;;; Interrupted function. $EINTR - ;; Invalid argument. + ;;; Invalid argument. $EINVAL - ;; I/O error. + ;;; I/O error. $EIO - ;; Socket is connected. + ;;; Socket is connected. $EISCONN - ;; Is a directory. + ;;; Is a directory. $EISDIR - ;; Too many levels of symbolic links. + ;;; Too many levels of symbolic links. $ELOOP - ;; File descriptor value too large. + ;;; File descriptor value too large. $EMFILE - ;; Too many links. + ;;; Too many links. $EMLINK - ;; Message too large. + ;;; Message too large. $EMSGSIZE - ;; Reserved. + ;;; Reserved. $EMULTIHOP - ;; Filename too long. + ;;; Filename too long. $ENAMETOOLONG - ;; Network is down. + ;;; Network is down. $ENETDOWN - ;; Connection aborted by network. + ;;; Connection aborted by network. $ENETRESET - ;; Network unreachable. + ;;; Network unreachable. $ENETUNREACH - ;; Too many files open in system. + ;;; Too many files open in system. $ENFILE - ;; No buffer space available. + ;;; No buffer space available. $ENOBUFS - ;; No such device. + ;;; No such device. $ENODEV - ;; No such file or directory. + ;;; No such file or directory. $ENOENT - ;; Executable file format error. + ;;; Executable file format error. $ENOEXEC - ;; No locks available. + ;;; No locks available. $ENOLCK - ;; Reserved. + ;;; Reserved. $ENOLINK - ;; Not enough space. + ;;; Not enough space. $ENOMEM - ;; No message of the desired type. + ;;; No message of the desired type. $ENOMSG - ;; Protocol not available. + ;;; Protocol not available. $ENOPROTOOPT - ;; No space left on device. + ;;; No space left on device. $ENOSPC - ;; Function not supported. + ;;; Function not supported. $ENOSYS - ;; The socket is not connected. + ;;; The socket is not connected. $ENOTCONN - ;; Not a directory or a symbolic link to a directory. + ;;; Not a directory or a symbolic link to a directory. $ENOTDIR - ;; Directory not empty. + ;;; Directory not empty. $ENOTEMPTY - ;; State not recoverable. + ;;; State not recoverable. $ENOTRECOVERABLE - ;; Not a socket. + ;;; Not a socket. $ENOTSOCK - ;; Not supported, or operation not supported on socket. + ;;; Not supported, or operation not supported on socket. $ENOTSUP - ;; Inappropriate I/O control operation. + ;;; Inappropriate I/O control operation. $ENOTTY - ;; No such device or address. + ;;; No such device or address. $ENXIO - ;; Value too large to be stored in data type. + ;;; Value too large to be stored in data type. $EOVERFLOW - ;; Previous owner died. + ;;; Previous owner died. $EOWNERDEAD - ;; Operation not permitted. + ;;; Operation not permitted. $EPERM - ;; Broken pipe. + ;;; Broken pipe. $EPIPE - ;; Protocol error. + ;;; Protocol error. $EPROTO - ;; Protocol not supported. + ;;; Protocol not supported. $EPROTONOSUPPORT - ;; Protocol wrong type for socket. + ;;; Protocol wrong type for socket. $EPROTOTYPE - ;; Result too large. + ;;; Result too large. $ERANGE - ;; Read-only file system. + ;;; Read-only file system. $EROFS - ;; Invalid seek. + ;;; Invalid seek. $ESPIPE - ;; No such process. + ;;; No such process. $ESRCH - ;; Reserved. + ;;; Reserved. $ESTALE - ;; Connection timed out. + ;;; Connection timed out. $ETIMEDOUT - ;; Text file busy. + ;;; Text file busy. $ETXTBSY - ;; Cross-device link. + ;;; Cross-device link. $EXDEV - ;; Extension: Capabilities insufficient. + ;;; Extension: Capabilities insufficient. $ENOTCAPABLE ) ) -;; File descriptor rights, determining which actions may be performed. +;;; File descriptor rights, determining which actions may be performed. (typename $rights_t (flags u64 - ;; The right to invoke `fd_datasync`. + ;;; The right to invoke `fd_datasync`. ;; - ;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke - ;; `path_open` with `FDFLAG_DSYNC`. + ;;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke + ;;; `path_open` with `FDFLAG_DSYNC`. $RIGHT_FD_DATASYNC - ;; The right to invoke `fd_read` and `sock_recv`. + ;;; The right to invoke `fd_read` and `sock_recv`. ;; - ;; If `RIGHT_FD_SEEK` is set, includes the right to invoke `fd_pread`. + ;;; If `RIGHT_FD_SEEK` is set, includes the right to invoke `fd_pread`. $RIGHT_FD_READ - ;; The right to invoke `fd_seek`. This flag implies `RIGHT_FD_TELL`. + ;;; The right to invoke `fd_seek`. This flag implies `RIGHT_FD_TELL`. $RIGHT_FD_SEEK - ;; The right to invoke `fd_fdstat_set_flags`. + ;;; The right to invoke `fd_fdstat_set_flags`. $RIGHT_FD_FDSTAT_SET_FLAGS - ;; The right to invoke `fd_sync`. + ;;; The right to invoke `fd_sync`. ;; - ;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke - ;; `path_open` with `FDFLAG_RSYNC` and `FDFLAG_DSYNC`. + ;;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke + ;;; `path_open` with `FDFLAG_RSYNC` and `FDFLAG_DSYNC`. $RIGHT_FD_SYNC - ;; The right to invoke `fd_seek` in such a way that the file offset - ;; remains unaltered (i.e., `WHENCE_CUR` with offset zero), or to - ;; invoke `fd_tell`. + ;;; The right to invoke `fd_seek` in such a way that the file offset + ;;; remains unaltered (i.e., `WHENCE_CUR` with offset zero), or to + ;;; invoke `fd_tell`. $RIGHT_FD_TELL - ;; The right to invoke `fd_write` and `sock_send`. - ;; If `RIGHT_FD_SEEK` is set, includes the right to invoke `fd_pwrite`. + ;;; The right to invoke `fd_write` and `sock_send`. + ;;; If `RIGHT_FD_SEEK` is set, includes the right to invoke `fd_pwrite`. $RIGHT_FD_WRITE - ;; The right to invoke `fd_advise`. + ;;; The right to invoke `fd_advise`. $RIGHT_FD_ADVISE - ;; The right to invoke `fd_allocate`. + ;;; The right to invoke `fd_allocate`. $RIGHT_FD_ALLOCATE - ;; The right to invoke `path_create_directory`. + ;;; The right to invoke `path_create_directory`. $RIGHT_PATH_CREATE_DIRECTORY - ;; If `RIGHT_PATH_OPEN` is set, the right to invoke `path_open` with `O_CREAT`. + ;;; If `RIGHT_PATH_OPEN` is set, the right to invoke `path_open` with `O_CREAT`. $RIGHT_PATH_CREATE_FILE - ;; The right to invoke `path_link` with the file descriptor as the - ;; source directory. + ;;; The right to invoke `path_link` with the file descriptor as the + ;;; source directory. $RIGHT_PATH_LINK_SOURCE - ;; The right to invoke `path_link` with the file descriptor as the - ;; target directory. + ;;; The right to invoke `path_link` with the file descriptor as the + ;;; target directory. $RIGHT_PATH_LINK_TARGET - ;; The right to invoke `path_open`. + ;;; The right to invoke `path_open`. $RIGHT_PATH_OPEN - ;; The right to invoke `fd_readdir`. + ;;; The right to invoke `fd_readdir`. $RIGHT_FD_READDIR - ;; The right to invoke `path_readlink`. + ;;; The right to invoke `path_readlink`. $RIGHT_PATH_READLINK - ;; The right to invoke `path_rename` with the file descriptor as the source directory. + ;;; The right to invoke `path_rename` with the file descriptor as the source directory. $RIGHT_PATH_RENAME_SOURCE - ;; The right to invoke `path_rename` with the file descriptor as the target directory. + ;;; The right to invoke `path_rename` with the file descriptor as the target directory. $RIGHT_PATH_RENAME_TARGET - ;; The right to invoke `path_filestat_get`. + ;;; The right to invoke `path_filestat_get`. $RIGHT_PATH_FILESTAT_GET - ;; The right to change a file's size (there is no `path_filestat_set_size`). - ;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke `path_open` with `O_TRUNC`. + ;;; The right to change a file's size (there is no `path_filestat_set_size`). + ;;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke `path_open` with `O_TRUNC`. $RIGHT_PATH_FILESTAT_SET_SIZE - ;; The right to invoke `path_filestat_set_times`. + ;;; The right to invoke `path_filestat_set_times`. $RIGHT_PATH_FILESTAT_SET_TIMES - ;; The right to invoke `fd_filestat_get`. + ;;; The right to invoke `fd_filestat_get`. $RIGHT_FD_FILESTAT_GET - ;; The right to invoke `fd_filestat_set_size`. + ;;; The right to invoke `fd_filestat_set_size`. $RIGHT_FD_FILESTAT_SET_SIZE - ;; The right to invoke `fd_filestat_set_times`. + ;;; The right to invoke `fd_filestat_set_times`. $RIGHT_FD_FILESTAT_SET_TIMES - ;; The right to invoke `path_symlink`. + ;;; The right to invoke `path_symlink`. $RIGHT_PATH_SYMLINK - ;; The right to invoke `path_remove_directory`. + ;;; The right to invoke `path_remove_directory`. $RIGHT_PATH_REMOVE_DIRECTORY - ;; The right to invoke `path_unlink_file`. + ;;; The right to invoke `path_unlink_file`. $RIGHT_PATH_UNLINK_FILE - ;; If `RIGHT_FD_READ` is set, includes the right to invoke `poll_oneoff` to subscribe to `EVENTTYPE_FD_READ`. - ;; If `RIGHT_FD_WRITE` is set, includes the right to invoke `poll_oneoff` to subscribe to `EVENTTYPE_FD_WRITE`. + ;;; If `RIGHT_FD_READ` is set, includes the right to invoke `poll_oneoff` to subscribe to `EVENTTYPE_FD_READ`. + ;;; If `RIGHT_FD_WRITE` is set, includes the right to invoke `poll_oneoff` to subscribe to `EVENTTYPE_FD_WRITE`. $RIGHT_POLL_FD_READWRITE - ;; The right to invoke `sock_shutdown`. + ;;; The right to invoke `sock_shutdown`. $RIGHT_SOCK_SHUTDOWN ) ) -;; A file descriptor index. +;;; A file descriptor index. (typename $fd_t u32) -;; A region of memory for scatter/gather reads. +;;; A region of memory for scatter/gather reads. (typename $iovec_t (struct - ;; The address of the buffer to be filled. + ;;; The address of the buffer to be filled. (field $buf (@witx pointer u8)) - ;; The length of the buffer to be filled. + ;;; The length of the buffer to be filled. (field $buf_len $size_t) ) ) -;; A region of memory for scatter/gather writes. +;;; A region of memory for scatter/gather writes. (typename $ciovec_t (struct - ;; The address of the buffer to be written. + ;;; The address of the buffer to be written. (field $buf (@witx const_pointer u8)) - ;; The length of the buffer to be written. + ;;; The length of the buffer to be written. (field $buf_len $size_t) ) ) @@ -299,469 +299,469 @@ (typename $iovec_t_array (array $iovec_t)) (typename $ciovec_t_array (array $ciovec_t)) -;; Relative offset within a file. +;;; Relative offset within a file. (typename $filedelta_t s64) -;; The position relative to which to set the offset of the file descriptor. +;;; The position relative to which to set the offset of the file descriptor. (typename $whence_t (enum u8 - ;; Seek relative to start-of-file. + ;;; Seek relative to start-of-file. $WHENCE_SET - ;; Seek relative to current position. + ;;; Seek relative to current position. $WHENCE_CUR - ;; Seek relative to end-of-file. + ;;; Seek relative to end-of-file. $WHENCE_END ) ) -;; A reference to the offset of a directory entry. +;;; A reference to the offset of a directory entry. ;; -;; The value 0 signifies the start of the directory. +;;; The value 0 signifies the start of the directory. (typename $dircookie_t u64) -;; The type for the $d_namlen field of $dirent_t. +;;; The type for the $d_namlen field of $dirent_t. (typename $dirnamlen_t u32) -;; File serial number that is unique within its file system. +;;; File serial number that is unique within its file system. (typename $inode_t u64) -;; The type of a file descriptor or file. +;;; The type of a file descriptor or file. (typename $filetype_t (enum u8 - ;; The type of the file descriptor or file is unknown or is different from any of the other types specified. + ;;; The type of the file descriptor or file is unknown or is different from any of the other types specified. $FILETYPE_UNKNOWN - ;; The file descriptor or file refers to a block device inode. + ;;; The file descriptor or file refers to a block device inode. $FILETYPE_BLOCK_DEVICE - ;; The file descriptor or file refers to a character device inode. + ;;; The file descriptor or file refers to a character device inode. $FILETYPE_CHARACTER_DEVICE - ;; The file descriptor or file refers to a directory inode. + ;;; The file descriptor or file refers to a directory inode. $FILETYPE_DIRECTORY - ;; The file descriptor or file refers to a regular file inode. + ;;; The file descriptor or file refers to a regular file inode. $FILETYPE_REGULAR_FILE - ;; The file descriptor or file refers to a datagram socket. + ;;; The file descriptor or file refers to a datagram socket. $FILETYPE_SOCKET_DGRAM - ;; The file descriptor or file refers to a byte-stream socket. + ;;; The file descriptor or file refers to a byte-stream socket. $FILETYPE_SOCKET_STREAM - ;; The file refers to a symbolic link inode. + ;;; The file refers to a symbolic link inode. $FILETYPE_SYMBOLIC_LINK ) ) -;; A directory entry. +;;; A directory entry. (typename $dirent_t (struct - ;; The offset of the next directory entry stored in this directory. + ;;; The offset of the next directory entry stored in this directory. (field $d_next $dircookie_t) - ;; The serial number of the file referred to by this directory entry. + ;;; The serial number of the file referred to by this directory entry. (field $d_ino $inode_t) - ;; The length of the name of the directory entry. + ;;; The length of the name of the directory entry. (field $d_namlen $dirnamlen_t) - ;; The type of the file referred to by this directory entry. + ;;; The type of the file referred to by this directory entry. (field $d_type $filetype_t) ) ) -;; File or memory access pattern advisory information. +;;; File or memory access pattern advisory information. (typename $advice_t (enum u8 - ;; The application has no advice to give on its behavior with respect to the specified data. + ;;; The application has no advice to give on its behavior with respect to the specified data. $ADVICE_NORMAL - ;; The application expects to access the specified data sequentially from lower offsets to higher offsets. + ;;; The application expects to access the specified data sequentially from lower offsets to higher offsets. $ADVICE_SEQUENTIAL - ;; The application expects to access the specified data in a random order. + ;;; The application expects to access the specified data in a random order. $ADVICE_RANDOM - ;; The application expects to access the specified data in the near future. + ;;; The application expects to access the specified data in the near future. $ADVICE_WILLNEED - ;; The application expects that it will not access the specified data in the near future. + ;;; The application expects that it will not access the specified data in the near future. $ADVICE_DONTNEED - ;; The application expects to access the specified data once and then not reuse it thereafter. + ;;; The application expects to access the specified data once and then not reuse it thereafter. $ADVICE_NOREUSE ) ) -;; File descriptor flags. +;;; File descriptor flags. (typename $fdflags_t (flags u16 - ;; Append mode: Data written to the file is always appended to the file's end. + ;;; Append mode: Data written to the file is always appended to the file's end. $FDFLAG_APPEND - ;; Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized. + ;;; Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized. $FDFLAG_DSYNC - ;; Non-blocking mode. + ;;; Non-blocking mode. $FDFLAG_NONBLOCK - ;; Synchronized read I/O operations. + ;;; Synchronized read I/O operations. $FDFLAG_RSYNC - ;; Write according to synchronized I/O file integrity completion. In - ;; addition to synchronizing the data stored in the file, the implementation - ;; may also synchronously update the file's metadata. + ;;; Write according to synchronized I/O file integrity completion. In + ;;; addition to synchronizing the data stored in the file, the implementation + ;;; may also synchronously update the file's metadata. $FDFLAG_SYNC ) ) -;; File descriptor attributes. +;;; File descriptor attributes. (typename $fdstat_t (struct - ;; File type. + ;;; File type. (field $fs_filetype $filetype_t) - ;; File descriptor flags. + ;;; File descriptor flags. (field $fs_flags $fdflags_t) - ;; Rights that apply to this file descriptor. + ;;; Rights that apply to this file descriptor. (field $fs_rights_base $rights_t) - ;; Maximum set of rights that may be installed on new file descriptors that - ;; are created through this file descriptor, e.g., through `path_open`. + ;;; Maximum set of rights that may be installed on new file descriptors that + ;;; are created through this file descriptor, e.g., through `path_open`. (field $fs_rights_inheriting $rights_t) ) ) -;; Identifier for a device containing a file system. Can be used in combination -;; with `inode_t` to uniquely identify a file or directory in the filesystem. +;;; Identifier for a device containing a file system. Can be used in combination +;;; with `inode_t` to uniquely identify a file or directory in the filesystem. (typename $device_t u64) -;; Which file time attributes to adjust. +;;; Which file time attributes to adjust. (typename $fstflags_t (flags u16 - ;; Adjust the last data access timestamp to the value stored in `filestat_t::st_atim`. + ;;; Adjust the last data access timestamp to the value stored in `filestat_t::st_atim`. $FILESTAT_SET_ATIM - ;; Adjust the last data access timestamp to the time of clock `CLOCK_REALTIME`. + ;;; Adjust the last data access timestamp to the time of clock `CLOCK_REALTIME`. $FILESTAT_SET_ATIM_NOW - ;; Adjust the last data modification timestamp to the value stored in `filestat_t::st_mtim`. + ;;; Adjust the last data modification timestamp to the value stored in `filestat_t::st_mtim`. $FILESTAT_SET_MTIM - ;; Adjust the last data modification timestamp to the time of clock `CLOCK_REALTIME`. + ;;; Adjust the last data modification timestamp to the time of clock `CLOCK_REALTIME`. $FILESTAT_SET_MTIM_NOW ) ) -;; Flags determining the method of how paths are resolved. +;;; Flags determining the method of how paths are resolved. (typename $lookupflags_t (flags u32 - ;; As long as the resolved path corresponds to a symbolic link, it is expanded. + ;;; As long as the resolved path corresponds to a symbolic link, it is expanded. $LOOKUP_SYMLINK_FOLLOW ) ) -;; Open flags used by `path_open`. +;;; Open flags used by `path_open`. (typename $oflags_t (flags u16 - ;; Create file if it does not exist. + ;;; Create file if it does not exist. $O_CREAT - ;; Fail if not a directory. + ;;; Fail if not a directory. $O_DIRECTORY - ;; Fail if file already exists. + ;;; Fail if file already exists. $O_EXCL - ;; Truncate file to size 0. + ;;; Truncate file to size 0. $O_TRUNC ) ) -;; Number of hard links to an inode. +;;; Number of hard links to an inode. (typename $linkcount_t u64) -;; File attributes. +;;; File attributes. (typename $filestat_t (struct - ;; Device ID of device containing the file. + ;;; Device ID of device containing the file. (field $st_dev $device_t) - ;; File serial number. + ;;; File serial number. (field $st_ino $inode_t) - ;; File type. + ;;; File type. (field $st_filetype $filetype_t) - ;; Number of hard links to the file. + ;;; Number of hard links to the file. (field $st_nlink $linkcount_t) - ;; For regular files, the file size in bytes. For symbolic links, the length in bytes of the pathname contained in the symbolic link. + ;;; For regular files, the file size in bytes. For symbolic links, the length in bytes of the pathname contained in the symbolic link. (field $st_size $filesize_t) - ;; Last data access timestamp. + ;;; Last data access timestamp. (field $st_atim $timestamp_t) - ;; Last data modification timestamp. + ;;; Last data modification timestamp. (field $st_mtim $timestamp_t) - ;; Last file status change timestamp. + ;;; Last file status change timestamp. (field $st_ctim $timestamp_t) ) ) -;; User-provided value that may be attached to objects that is retained when -;; extracted from the implementation. +;;; User-provided value that may be attached to objects that is retained when +;;; extracted from the implementation. (typename $userdata_t u64) -;; Type of a subscription to an event or its occurrence. +;;; Type of a subscription to an event or its occurrence. (typename $eventtype_t (enum u8 - ;; The time value of clock `subscription_t::u.clock.clock_id` has - ;; reached timestamp `subscription_t::u.clock.timeout`. + ;;; The time value of clock `subscription_t::u.clock.clock_id` has + ;;; reached timestamp `subscription_t::u.clock.timeout`. $EVENTTYPE_CLOCK - ;; File descriptor `subscription_t::u.fd_readwrite.fd` has data - ;; available for reading. This event always triggers for regular files. + ;;; File descriptor `subscription_t::u.fd_readwrite.fd` has data + ;;; available for reading. This event always triggers for regular files. $EVENTTYPE_FD_READ - ;; File descriptor `subscription_t::u.fd_readwrite.fd` has capacity - ;; available for writing. This event always triggers for regular files. + ;;; File descriptor `subscription_t::u.fd_readwrite.fd` has capacity + ;;; available for writing. This event always triggers for regular files. $EVENTTYPE_FD_WRITE ) ) -;; The state of the file descriptor subscribed to with -;; `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`. +;;; The state of the file descriptor subscribed to with +;;; `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`. (typename $eventrwflags_t (flags u16 - ;; The peer of this socket has closed or disconnected. + ;;; The peer of this socket has closed or disconnected. $EVENT_FD_READWRITE_HANGUP ) ) -;; The contents of an $event_t when type is `EVENTTYPE_FD_READ` or -;; `EVENTTYPE_FD_WRITE`. +;;; The contents of an $event_t when type is `EVENTTYPE_FD_READ` or +;;; `EVENTTYPE_FD_WRITE`. (typename $event_fd_readwrite_t (struct - ;; The number of bytes available for reading or writing. + ;;; The number of bytes available for reading or writing. (field $nbytes $filesize_t) - ;; The state of the file descriptor. + ;;; The state of the file descriptor. (field $flags $eventrwflags_t) ) ) -;; The contents of an $event_t. +;;; The contents of an $event_t. (typename $event_u (union - ;; When type is `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`: + ;;; When type is `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`: (field $fd_readwrite $event_fd_readwrite_t) ) ) -;; An event that occurred. +;;; An event that occurred. (typename $event_t (struct - ;; User-provided value that got attached to `subscription_t::userdata`. + ;;; User-provided value that got attached to `subscription_t::userdata`. (field $userdata $userdata_t) - ;; If non-zero, an error that occurred while processing the subscription request. + ;;; If non-zero, an error that occurred while processing the subscription request. (field $error $errno_t) - ;; The type of the event that occurred. + ;;; The type of the event that occurred. (field $type $eventtype_t) - ;; The contents of the event. + ;;; The contents of the event. (field $u $event_u) ) ) -;; Flags determining how to interpret the timestamp provided in -;; `subscription_t::u.clock.timeout.` +;;; Flags determining how to interpret the timestamp provided in +;;; `subscription_t::u.clock.timeout.` (typename $subclockflags_t (flags u16 - ;; If set, treat the timestamp provided in - ;; `subscription_t::u.clock.timeout` as an absolute timestamp of clock - ;; `subscription_t::u.clock.clock_id.` If clear, treat the timestamp - ;; provided in `subscription_t::u.clock.timeout` relative to the - ;; current time value of clock `subscription_t::u.clock.clock_id.` + ;;; If set, treat the timestamp provided in + ;;; `subscription_t::u.clock.timeout` as an absolute timestamp of clock + ;;; `subscription_t::u.clock.clock_id.` If clear, treat the timestamp + ;;; provided in `subscription_t::u.clock.timeout` relative to the + ;;; current time value of clock `subscription_t::u.clock.clock_id.` $SUBSCRIPTION_CLOCK_ABSTIME ) ) -;; The contents of a $subscription_t when type is `EVENTTYPE_CLOCK`. +;;; The contents of a $subscription_t when type is `EVENTTYPE_CLOCK`. (typename $subscription_clock_t (struct - ;; The clock against which to compare the timestamp. + ;;; The clock against which to compare the timestamp. (field $clock_id $clockid_t) - ;; The absolute or relative timestamp. + ;;; The absolute or relative timestamp. (field $timeout $timestamp_t) - ;; The amount of time that the implementation may wait additionally - ;; to coalesce with other events. + ;;; The amount of time that the implementation may wait additionally + ;;; to coalesce with other events. (field $precision $timestamp_t) - ;; Flags specifying whether the timeout is absolute or relative + ;;; Flags specifying whether the timeout is absolute or relative (field $flags $subclockflags_t) ) ) -;; The contents of a $subscription_t when type is type is -;; `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`. +;;; The contents of a $subscription_t when type is type is +;;; `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`. (typename $subscription_fd_readwrite_t (struct - ;; The file descriptor on which to wait for it to become ready for reading or writing. + ;;; The file descriptor on which to wait for it to become ready for reading or writing. (field $file_descriptor $fd_t) ) ) -;; The contents of a $subscription_t. +;;; The contents of a $subscription_t. (typename $subscription_u (union - ;; When type is `EVENTTYPE_CLOCK`: + ;;; When type is `EVENTTYPE_CLOCK`: (field $clock $subscription_clock_t) - ;; When type is `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`: + ;;; When type is `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`: (field $fd_readwrite $subscription_fd_readwrite_t) ) ) -;; Subscription to an event. +;;; Subscription to an event. (typename $subscription_t (struct - ;; User-provided value that is attached to the subscription in the - ;; implementation and returned through `event_t::userdata`. + ;;; User-provided value that is attached to the subscription in the + ;;; implementation and returned through `event_t::userdata`. (field $userdata $userdata_t) - ;; The type of the event to which to subscribe. + ;;; The type of the event to which to subscribe. (field $type $eventtype_t) - ;; The contents of the subscription. + ;;; The contents of the subscription. (field $u $subscription_u) ) ) -;; Exit code generated by a process when exiting. +;;; Exit code generated by a process when exiting. (typename $exitcode_t u32) -;; Signal condition. +;;; Signal condition. (typename $signal_t (enum u8 - ;; No signal. Note that POSIX has special semantics for `kill(pid, 0)`, - ;; so this value is reserved. + ;;; No signal. Note that POSIX has special semantics for `kill(pid, 0)`, + ;;; so this value is reserved. $SIGNONE - ;; Hangup. - ;; Action: Terminates the process. + ;;; Hangup. + ;;; Action: Terminates the process. $SIGHUP - ;; Terminate interrupt signal. - ;; Action: Terminates the process. + ;;; Terminate interrupt signal. + ;;; Action: Terminates the process. $SIGINT - ;; Terminal quit signal. - ;; Action: Terminates the process. + ;;; Terminal quit signal. + ;;; Action: Terminates the process. $SIGQUIT - ;; Illegal instruction. - ;; Action: Terminates the process. + ;;; Illegal instruction. + ;;; Action: Terminates the process. $SIGILL - ;; Trace/breakpoint trap. - ;; Action: Terminates the process. + ;;; Trace/breakpoint trap. + ;;; Action: Terminates the process. $SIGTRAP - ;; Process abort signal. - ;; Action: Terminates the process. + ;;; Process abort signal. + ;;; Action: Terminates the process. $SIGABRT - ;; Access to an undefined portion of a memory object. - ;; Action: Terminates the process. + ;;; Access to an undefined portion of a memory object. + ;;; Action: Terminates the process. $SIGBUS - ;; Erroneous arithmetic operation. - ;; Action: Terminates the process. + ;;; Erroneous arithmetic operation. + ;;; Action: Terminates the process. $SIGFPE - ;; Kill. - ;; Action: Terminates the process. + ;;; Kill. + ;;; Action: Terminates the process. $SIGKILL - ;; User-defined signal 1. - ;; Action: Terminates the process. + ;;; User-defined signal 1. + ;;; Action: Terminates the process. $SIGUSR1 - ;; Invalid memory reference. - ;; Action: Terminates the process. + ;;; Invalid memory reference. + ;;; Action: Terminates the process. $SIGSEGV - ;; User-defined signal 2. - ;; Action: Terminates the process. + ;;; User-defined signal 2. + ;;; Action: Terminates the process. $SIGUSR2 - ;; Write on a pipe with no one to read it. - ;; Action: Ignored. + ;;; Write on a pipe with no one to read it. + ;;; Action: Ignored. $SIGPIPE - ;; Alarm clock. - ;; Action: Terminates the process. + ;;; Alarm clock. + ;;; Action: Terminates the process. $SIGALRM - ;; Termination signal. - ;; Action: Terminates the process. + ;;; Termination signal. + ;;; Action: Terminates the process. $SIGTERM - ;; Child process terminated, stopped, or continued. - ;; Action: Ignored. + ;;; Child process terminated, stopped, or continued. + ;;; Action: Ignored. $SIGCHLD - ;; Continue executing, if stopped. - ;; Action: Continues executing, if stopped. + ;;; Continue executing, if stopped. + ;;; Action: Continues executing, if stopped. $SIGCONT - ;; Stop executing. - ;; Action: Stops executing. + ;;; Stop executing. + ;;; Action: Stops executing. $SIGSTOP - ;; Terminal stop signal. - ;; Action: Stops executing. + ;;; Terminal stop signal. + ;;; Action: Stops executing. $SIGTSTP - ;; Background process attempting read. - ;; Action: Stops executing. + ;;; Background process attempting read. + ;;; Action: Stops executing. $SIGTTIN - ;; Background process attempting write. - ;; Action: Stops executing. + ;;; Background process attempting write. + ;;; Action: Stops executing. $SIGTTOU - ;; High bandwidth data is available at a socket. - ;; Action: Ignored. + ;;; High bandwidth data is available at a socket. + ;;; Action: Ignored. $SIGURG - ;; CPU time limit exceeded. - ;; Action: Terminates the process. + ;;; CPU time limit exceeded. + ;;; Action: Terminates the process. $SIGXCPU - ;; File size limit exceeded. - ;; Action: Terminates the process. + ;;; File size limit exceeded. + ;;; Action: Terminates the process. $SIGXFSZ - ;; Virtual timer expired. - ;; Action: Terminates the process. + ;;; Virtual timer expired. + ;;; Action: Terminates the process. $SIGVTALRM - ;; Profiling timer expired. - ;; Action: Terminates the process. + ;;; Profiling timer expired. + ;;; Action: Terminates the process. $SIGPROF - ;; Window changed. - ;; Action: Ignored. + ;;; Window changed. + ;;; Action: Ignored. $SIGWINCH - ;; I/O possible. - ;; Action: Terminates the process. + ;;; I/O possible. + ;;; Action: Terminates the process. $SIGPOLL - ;; Power failure. - ;; Action: Terminates the process. + ;;; Power failure. + ;;; Action: Terminates the process. $SIGPWR - ;; Bad system call. - ;; Action: Terminates the process. + ;;; Bad system call. + ;;; Action: Terminates the process. $SIGSYS ) ) -;; Flags provided to `sock_recv`. +;;; Flags provided to `sock_recv`. (typename $riflags_t (flags u16 - ;; Returns the message without removing it from the socket's receive queue. + ;;; Returns the message without removing it from the socket's receive queue. $SOCK_RECV_PEEK - ;; On byte-stream sockets, block until the full amount of data can be returned. + ;;; On byte-stream sockets, block until the full amount of data can be returned. $SOCK_RECV_WAITALL ) ) -;; Flags returned by `sock_recv`. +;;; Flags returned by `sock_recv`. (typename $roflags_t (flags u16 - ;; Returned by `sock_recv`: Message data has been truncated. + ;;; Returned by `sock_recv`: Message data has been truncated. $SOCK_RECV_DATA_TRUNCATED ) ) -;; Flags provided to `sock_send`. As there are currently no flags -;; defined, it must be set to zero. +;;; Flags provided to `sock_send`. As there are currently no flags +;;; defined, it must be set to zero. (typename $siflags_t u16) -;; Which channels on a socket to shut down. +;;; Which channels on a socket to shut down. (typename $sdflags_t (flags u8 - ;; Disables further receive operations. + ;;; Disables further receive operations. $SHUT_RD - ;; Disables further send operations. + ;;; Disables further send operations. $SHUT_WR ) ) -;; Identifiers for preopened capabilities. +;;; Identifiers for preopened capabilities. (typename $preopentype_t (enum u8 - ;; A pre-opened directory. + ;;; A pre-opened directory. $PREOPENTYPE_DIR ) ) -;; The contents of a $prestat_t when type is `PREOPENTYPE_DIR`. +;;; The contents of a $prestat_t when type is `PREOPENTYPE_DIR`. (typename $prestat_dir (struct - ;; The length of the directory name for use with `fd_prestat_dir_name`. + ;;; The length of the directory name for use with `fd_prestat_dir_name`. (field $pr_name_len $size_t) ) ) -;; The contents of an $prestat_t. +;;; The contents of an $prestat_t. (typename $prestat_u (union - ;; When type is `PREOPENTYPE_DIR`: + ;;; When type is `PREOPENTYPE_DIR`: (field $dir $prestat_dir) ) ) -;; Information about a pre-opened capability. +;;; Information about a pre-opened capability. (typename $prestat_t (struct - ;; The type of the pre-opened capability. + ;;; The type of the pre-opened capability. (field $pr_type $preopentype_t) - ;; The contents of the information. + ;;; The contents of the information. (field $u $prestat_u) ) ) diff --git a/phases/ephemeral/witx/wasi_ephemeral_preview.witx b/phases/ephemeral/witx/wasi_ephemeral_preview.witx index f98ff129b..d15b8c514 100644 --- a/phases/ephemeral/witx/wasi_ephemeral_preview.witx +++ b/phases/ephemeral/witx/wasi_ephemeral_preview.witx @@ -9,519 +9,522 @@ (use "typenames.witx") (module $wasi_ephemeral_preview - ;; Linear memory to be accessed by WASI functions that need it. + ;;; Linear memory to be accessed by WASI functions that need it. (import "memory" (memory)) - ;; Read command-line argument data. - ;; The size of the array should match that returned by `wasi_args_sizes_get()` + ;;; Read command-line argument data. + ;;; The size of the array should match that returned by `wasi_args_sizes_get()` (@interface func (export "args_get") (param $argv (@witx pointer (@witx pointer u8))) (param $argv_buf (@witx pointer u8)) (result $error $errno_t) ) - ;; Return command-line argument data sizes. + ;;; Return command-line argument data sizes. (@interface func (export "args_sizes_get") (result $error $errno_t) - ;; The number of arguments. + ;;; The number of arguments. (result $argc $size_t) - ;; The size of the argument string data. + ;;; The size of the argument string data. (result $argv_buf_size $size_t) ) - ;; Read environment variable data. - ;; The sizes of the buffers should match that returned by `environ.sizes_get()`. + ;;; Read environment variable data. + ;;; The sizes of the buffers should match that returned by `environ.sizes_get()`. (@interface func (export "environ_get") (param $environ (@witx pointer (@witx pointer u8))) (param $environ_buf (@witx pointer u8)) (result $error $errno_t) ) - ;; Return command-line argument data sizes. + ;;; Return command-line argument data sizes. (@interface func (export "environ_sizes_get") (result $error $errno_t) - ;; The number of arguments. + ;;; The number of arguments. (result $argc $size_t) - ;; The size of the argument string data. + ;;; The size of the argument string data. (result $argv_buf_size $size_t) ) - ;; Return the resolution of a clock. - ;; Implementations are required to provide a non-zero value for supported clocks. For unsupported clocks, return `WASI_EINVAL` - ;; Note: This is similar to `clock_getres` in POSIX. + ;;; Return the resolution of a clock. + ;;; Implementations are required to provide a non-zero value for supported clocks. For unsupported clocks, return `WASI_EINVAL` + ;;; Note: This is similar to `clock_getres` in POSIX. (@interface func (export "clock_res_get") (result $error $errno_t) - ;; The clock for which to return the resolution. + ;;; The clock for which to return the resolution. (param $clock_id $clockid_t) - ;; The resolution of the clock. + ;;; The resolution of the clock. (result $resolution $timestamp_t) ) - ;; Return the time value of a clock. - ;; Note: This is similar to `clock_gettime` in POSIX. + ;;; Return the time value of a clock. + ;;; Note: This is similar to `clock_gettime` in POSIX. (@interface func (export "clock_time_get") - ;; The clock for which to return the time. + ;;; The clock for which to return the time. (param $clock_id $clockid_t) - ;; The maximum lag (exclusive) that the returned time value may have, compared to its actual value. + ;;; The maximum lag (exclusive) that the returned time value may have, compared to its actual value. (param $precision $timestamp_t) (result $error $errno_t) - ;; The time value of the clock. + ;;; The time value of the clock. (result $time $timestamp_t) ) - ;; Provide file advisory information on a file descriptor. - ;; Note: This is similar to `posix_fadvise` in POSIX. + ;;; Provide file advisory information on a file descriptor. + ;;; Note: This is similar to `posix_fadvise` in POSIX. (@interface func (export "fd_advise") (param $fd $fd_t) - (param $offset $filesize_t) ;; The offset within the file to which the advisory applies. - (param $len $filesize_t) ;; The length of the region to which the advisory applies. - (param $advice $advice_t) ;; The advice. + ;;; The offset within the file to which the advisory applies. + (param $offset $filesize_t) + ;;; The length of the region to which the advisory applies. + (param $len $filesize_t) + ;;; The advice. + (param $advice $advice_t) (result $error $errno_t) ) - ;; Force the allocation of space in a file. - ;; Note: This is similar to `posix_fallocate` in POSIX. + ;;; Force the allocation of space in a file. + ;;; Note: This is similar to `posix_fallocate` in POSIX. (@interface func (export "fd_allocate") (param $fd $fd_t) - ;; The offset at which to start the allocation. + ;;; The offset at which to start the allocation. (param $offset $filesize_t) - ;; The length of the area that is allocated. + ;;; The length of the area that is allocated. (param $len $filesize_t) (result $error $errno_t) ) - ;; Close a file descriptor. - ;; Note: This is similar to `close` in POSIX. + ;;; Close a file descriptor. + ;;; Note: This is similar to `close` in POSIX. (@interface func (export "fd_close") (param $fd $fd_t) (result $error $errno_t) ) - ;; Synchronize the data of a file to disk. - ;; Note: This is similar to `fdatasync` in POSIX. + ;;; Synchronize the data of a file to disk. + ;;; Note: This is similar to `fdatasync` in POSIX. (@interface func (export "fd_datasync") (param $fd $fd_t) (result $error $errno_t) ) - ;; Get the attributes of a file descriptor. - ;; Note: This returns similar flags to `fsync(fd, F_GETFL)` in POSIX, as well as additional fields. + ;;; Get the attributes of a file descriptor. + ;;; Note: This returns similar flags to `fsync(fd, F_GETFL)` in POSIX, as well as additional fields. (@interface func (export "fd_fdstat_get") (param $fd $fd_t) (result $error $errno_t) - ;; The buffer where the file descriptor's attributes are stored. + ;;; The buffer where the file descriptor's attributes are stored. (result $stat $fdstat_t) ) - ;; Adjust the flags associated with a file descriptor. - ;; Note: This is similar to `fcntl(fd, F_SETFL, flags)` in POSIX. + ;;; Adjust the flags associated with a file descriptor. + ;;; Note: This is similar to `fcntl(fd, F_SETFL, flags)` in POSIX. (@interface func (export "fd_fdstat_set_flags") (param $fd $fd_t) - ;; The desired values of the file descriptor flags. + ;;; The desired values of the file descriptor flags. (param $flags $fdflags_t) (result $error $errno_t) ) - ;; Adjust the rights associated with a file descriptor. - ;; This can only be used to remove rights, and returns `ENOTCAPABLE` if called in a way that would attempt to add rights + ;;; Adjust the rights associated with a file descriptor. + ;;; This can only be used to remove rights, and returns `ENOTCAPABLE` if called in a way that would attempt to add rights (@interface func (export "fd_fdstat_set_rights") (param $fd $fd_t) - ;; The desired rights of the file descriptor. + ;;; The desired rights of the file descriptor. (param $fs_rights_base $rights_t) (param $fs_rights_inheriting $rights_t) (result $error $errno_t) ) - ;; Return the attributes of an open file. + ;;; Return the attributes of an open file. (@interface func (export "fd_filestat_get") (param $fd $fd_t) (result $error $errno_t) - ;; The buffer where the file's attributes are stored. + ;;; The buffer where the file's attributes are stored. (result $buf $filestat_t) ) - ;; Adjust the size of an open file. If this increases the file's size, the extra bytes are filled with zeros. - ;; Note: This is similar to `ftruncate` in POSIX. + ;;; Adjust the size of an open file. If this increases the file's size, the extra bytes are filled with zeros. + ;;; Note: This is similar to `ftruncate` in POSIX. (@interface func (export "fd_filestat_set_size") (param $fd $fd_t) - ;; The desired file size. + ;;; The desired file size. (param $st_size $filesize_t) (result $error $errno_t) ) - ;; Adjust the timestamps of an open file or directory. - ;; Note: This is similar to `futimens` in POSIX. + ;;; Adjust the timestamps of an open file or directory. + ;;; Note: This is similar to `futimens` in POSIX. (@interface func (export "fd_filestat_set_times") (param $fd $fd_t) - ;; The desired values of the data access timestamp. + ;;; The desired values of the data access timestamp. (param $st_atim $timestamp_t) - ;; The desired values of the data modification timestamp. + ;;; The desired values of the data modification timestamp. (param $st_mtim $timestamp_t) - ;; A bitmask indicating which timestamps to adjust. + ;;; A bitmask indicating which timestamps to adjust. (param $fst_flags $fstflags_t) (result $error $errno_t) ) - ;; Read from a file descriptor, without using and updating the file descriptor's offset. - ;; Note: This is similar to `preadv` in POSIX. + ;;; Read from a file descriptor, without using and updating the file descriptor's offset. + ;;; Note: This is similar to `preadv` in POSIX. (@interface func (export "fd_pread") (param $fd $fd_t) - ;; List of scatter/gather vectors in which to store data. + ;;; List of scatter/gather vectors in which to store data. (param $iovs $iovec_t_array) - ;; The offset within the file at which to read. + ;;; The offset within the file at which to read. (param $offset $filesize_t) (result $error $errno_t) - ;; The number of bytes read. + ;;; The number of bytes read. (result $nread $size_t) ) - ;; Return a description of the given preopened file descriptor. + ;;; Return a description of the given preopened file descriptor. (@interface func (export "fd_prestat_get") (param $fd $fd_t) (result $error $errno_t) - ;; The buffer where the description is stored. + ;;; The buffer where the description is stored. (result $buf $prestat_t) ) - ;; Return a description of the given preopened file descriptor. + ;;; Return a description of the given preopened file descriptor. (@interface func (export "fd_prestat_dir_name") (param $fd $fd_t) - ;; A buffer into which to write the preopened directory name. + ;;; A buffer into which to write the preopened directory name. (param $path (@witx pointer u8)) (param $path_len $size_t) (result $error $errno_t) ) - ;; Write to a file descriptor, without using and updating the file descriptor's offset. - ;; Note: This is similar to `pwritev` in POSIX. + ;;; Write to a file descriptor, without using and updating the file descriptor's offset. + ;;; Note: This is similar to `pwritev` in POSIX. (@interface func (export "fd_pwrite") (param $fd $fd_t) - ;; List of scatter/gather vectors from which to retrieve data. + ;;; List of scatter/gather vectors from which to retrieve data. (param $iovs $ciovec_t_array) - ;; The offset within the file at which to write. + ;;; The offset within the file at which to write. (param $offset $filesize_t) (result $error $errno_t) - ;; The number of bytes written. + ;;; The number of bytes written. (result $nwritten $size_t) ) - ;; Read from a file descriptor. - ;; Note: This is similar to `readv` in POSIX. + ;;; Read from a file descriptor. + ;;; Note: This is similar to `readv` in POSIX. (@interface func (export "fd_read") (param $fd $fd_t) - ;; List of scatter/gather vectors to which to store data. + ;;; List of scatter/gather vectors to which to store data. (param $iovs $iovec_t_array) (result $error $errno_t) - ;; The number of bytes read. + ;;; The number of bytes read. (result $nread $size_t) ) - ;; Read directory entries from a directory. - ;; When successful, the contents of the output buffer consist of a sequence of - ;; directory entries. Each directory entry consists of a dirent_t object, - ;; followed by dirent_t::d_namlen bytes holding the name of the directory - ;; entry. + ;;; Read directory entries from a directory. + ;;; When successful, the contents of the output buffer consist of a sequence of + ;;; directory entries. Each directory entry consists of a dirent_t object, + ;;; followed by dirent_t::d_namlen bytes holding the name of the directory + ;;; entry. ;; - ;; This function fills the output buffer as much as possible, potentially - ;; truncating the last directory entry. This allows the caller to grow its - ;; read buffer size in case it's too small to fit a single large directory - ;; entry, or skip the oversized directory entry. + ;;; This function fills the output buffer as much as possible, potentially + ;;; truncating the last directory entry. This allows the caller to grow its + ;;; read buffer size in case it's too small to fit a single large directory + ;;; entry, or skip the oversized directory entry. (@interface func (export "fd_readdir") (param $fd $fd_t) - ;; The buffer where directory entries are stored + ;;; The buffer where directory entries are stored (param $buf (@witx pointer u8)) (param $buf_len $size_t) - ;; The location within the directory to start reading + ;;; The location within the directory to start reading (param $cookie $dircookie_t) (result $error $errno_t) - ;; The number of bytes stored in the read buffer. If less than the size of the read buffer, the end of the directory has been reached. + ;;; The number of bytes stored in the read buffer. If less than the size of the read buffer, the end of the directory has been reached. (result $bufused $size_t) ) - ;; Atomically replace a file descriptor by renumbering another file descriptor. + ;;; Atomically replace a file descriptor by renumbering another file descriptor. ;; - ;; Due to the strong focus on thread safety, this environment does not provide - ;; a mechanism to duplicate or renumber a file descriptor to an arbitrary - ;; number, like `dup2()`. This would be prone to race conditions, as an actual - ;; file descriptor with the same number could be allocated by a different - ;; thread at the same time. + ;;; Due to the strong focus on thread safety, this environment does not provide + ;;; a mechanism to duplicate or renumber a file descriptor to an arbitrary + ;;; number, like `dup2()`. This would be prone to race conditions, as an actual + ;;; file descriptor with the same number could be allocated by a different + ;;; thread at the same time. ;; - ;; This function provides a way to atomically renumber file descriptors, which - ;; would disappear if `dup2()` were to be removed entirely. + ;;; This function provides a way to atomically renumber file descriptors, which + ;;; would disappear if `dup2()` were to be removed entirely. (@interface func (export "fd_renumber") (param $fd $fd_t) - ;; The file descriptor to overwrite. + ;;; The file descriptor to overwrite. (param $to $fd_t) (result $error $errno_t) ) - ;; Move the offset of a file descriptor. - ;; Note: This is similar to `lseek` in POSIX. + ;;; Move the offset of a file descriptor. + ;;; Note: This is similar to `lseek` in POSIX. (@interface func (export "fd_seek") (param $fd $fd_t) - ;; The number of bytes to move. + ;;; The number of bytes to move. (param $offset $filedelta_t) - ;; The base from which the offset is relative. + ;;; The base from which the offset is relative. (param $whence $whence_t) (result $error $errno_t) - ;; The new offset of the file descriptor, relative to the start of the file. + ;;; The new offset of the file descriptor, relative to the start of the file. (result $newoffset $filesize_t) ) - ;; Synchronize the data and metadata of a file to disk. - ;; Note: This is similar to `fsync` in POSIX. + ;;; Synchronize the data and metadata of a file to disk. + ;;; Note: This is similar to `fsync` in POSIX. (@interface func (export "fd_sync") (param $fd $fd_t) (result $error $errno_t) ) - ;; Return the current offset of a file descriptor. - ;; Note: This is similar to `lseek(fd, 0, SEEK_CUR)` in POSIX. + ;;; Return the current offset of a file descriptor. + ;;; Note: This is similar to `lseek(fd, 0, SEEK_CUR)` in POSIX. (@interface func (export "fd_tell") (param $fd $fd_t) (result $error $errno_t) - ;; The current offset of the file descriptor, relative to the start of the file. + ;;; The current offset of the file descriptor, relative to the start of the file. (result $offset $filesize_t) ) - ;; Write to a file descriptor. - ;; Note: This is similar to `writev` in POSIX. + ;;; Write to a file descriptor. + ;;; Note: This is similar to `writev` in POSIX. (@interface func (export "fd_write") (param $fd $fd_t) - ;; List of scatter/gather vectors from which to retrieve data. + ;;; List of scatter/gather vectors from which to retrieve data. (param $iovs $ciovec_t_array) (result $error $errno_t) - ;; The number of bytes written. + ;;; The number of bytes written. (result $nwritten $size_t) ) - ;; Create a directory. - ;; Note: This is similar to `mkdirat` in POSIX. + ;;; Create a directory. + ;;; Note: This is similar to `mkdirat` in POSIX. (@interface func (export "path_create_directory") (param $fd $fd_t) - ;; The path at which to create the directory. + ;;; The path at which to create the directory. (param $path string) (result $error $errno_t) ) - ;; Return the attributes of a file or directory. - ;; Note: This is similar to `stat` in POSIX. + ;;; Return the attributes of a file or directory. + ;;; Note: This is similar to `stat` in POSIX. (@interface func (export "path_filestat_get") (param $fd $fd_t) - ;; Flags determining the method of how the path is resolved. + ;;; Flags determining the method of how the path is resolved. (param $flags $lookupflags_t) - ;; The path of the file or directory to inspect. + ;;; The path of the file or directory to inspect. (param $path string) (result $error $errno_t) - ;; The buffer where the file's attributes are stored. + ;;; The buffer where the file's attributes are stored. (result $buf $filestat_t) ) - ;; Adjust the timestamps of a file or directory. - ;; Note: This is similar to `utimensat` in POSIX. + ;;; Adjust the timestamps of a file or directory. + ;;; Note: This is similar to `utimensat` in POSIX. (@interface func (export "path_filestat_set_times") (param $fd $fd_t) - ;; Flags determining the method of how the path is resolved. + ;;; Flags determining the method of how the path is resolved. (param $flags $lookupflags_t) - ;; The path of the file or directory to operate on. + ;;; The path of the file or directory to operate on. (param $path string) - ;; The desired values of the data access timestamp. + ;;; The desired values of the data access timestamp. (param $st_atim $timestamp_t) - ;; The desired values of the data modification timestamp. + ;;; The desired values of the data modification timestamp. (param $st_mtim $timestamp_t) - ;; A bitmask indicating which timestamps to adjust. + ;;; A bitmask indicating which timestamps to adjust. (param $fst_flags $fstflags_t) (result $error $errno_t) ) - ;; Create a hard link. - ;; Note: This is similar to `linkat` in POSIX. + ;;; Create a hard link. + ;;; Note: This is similar to `linkat` in POSIX. (@interface func (export "path_link") (param $old_fd $fd_t) - ;; Flags determining the method of how the path is resolved. + ;;; Flags determining the method of how the path is resolved. (param $old_flags $lookupflags_t) - ;; The source path from which to link. + ;;; The source path from which to link. (param $old_path string) - ;; The working directory at which the resolution of the new path starts. + ;;; The working directory at which the resolution of the new path starts. (param $new_fd $fd_t) - ;; The destination path at which to create the hard link. + ;;; The destination path at which to create the hard link. (param $new_path string) (result $error $errno_t) ) - ;; Open a file or directory. + ;;; Open a file or directory. ;; - ;; The returned file descriptor is not guaranteed to be the lowest-numbered - ;; file 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 file descriptor is - ;; guaranteed to be less than 2**31. + ;;; The returned file descriptor is not guaranteed to be the lowest-numbered + ;;; file 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 file descriptor is + ;;; guaranteed to be less than 2**31. ;; - ;; Note: This is similar to `openat` in POSIX. + ;;; Note: This is similar to `openat` in POSIX. (@interface func (export "path_open") (param $fd $fd_t) - ;; Flags determining the method of how the path is resolved. + ;;; Flags determining the method of how the path is resolved. (param $dirflags $lookupflags_t) - ;; The relative path of the file or directory to open, relative to the - ;; `dirfd` directory. + ;;; The relative path of the file or directory to open, relative to the + ;;; `dirfd` directory. (param $path string) - ;; The method by which to open the file. + ;;; The method by which to open the file. (param $o_flags $oflags_t) - ;; The initial 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 initial 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 *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. (param $fs_rights_base $rights_t) (param $fs_rights_inherting $rights_t) (param $flags $fdflags_t) (result $error $errno_t) - ;; The file descriptor of the file that has been opened. + ;;; The file descriptor of the file that has been opened. (result $opened_fd $fd_t) ) - ;; Read the contents of a symbolic link. - ;; Note: This is similar to `readlinkat` in POSIX. + ;;; Read the contents of a symbolic link. + ;;; Note: This is similar to `readlinkat` in POSIX. (@interface func (export "path_readlink") (param $fd $fd_t) - ;; The path of the symbolic link from which to read. + ;;; The path of the symbolic link from which to read. (param $path string) - ;; The buffer to which to write the contents of the symbolic link. + ;;; The buffer to which to write the contents of the symbolic link. (param $buf (@witx pointer u8)) (param $buf_len $size_t) (result $error $errno_t) - ;; The number of bytes placed in the buffer. + ;;; The number of bytes placed in the buffer. (result $bufused $size_t) ) - ;; Remove a directory. - ;; Return `ENOTEMPTY` if the directory is not empty. - ;; Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX. + ;;; Remove a directory. + ;;; Return `ENOTEMPTY` if the directory is not empty. + ;;; Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX. (@interface func (export "path_remove_directory") (param $fd $fd_t) - ;; The path to a directory to remove. + ;;; The path to a directory to remove. (param $path string) (result $error $errno_t) ) - ;; Rename a file or directory. - ;; Note: This is similar to `renameat` in POSIX. + ;;; Rename a file or directory. + ;;; Note: This is similar to `renameat` in POSIX. (@interface func (export "path_rename") (param $fd $fd_t) - ;; The source path of the file or directory to rename. + ;;; The source path of the file or directory to rename. (param $old_path string) - ;; The working directory at which the resolution of the new path starts. + ;;; The working directory at which the resolution of the new path starts. (param $new_fd $fd_t) - ;; The destination path to which to rename the file or directory. + ;;; The destination path to which to rename the file or directory. (param $new_path string) (result $error $errno_t) ) - ;; Create a symbolic link. - ;; Note: This is similar to `symlinkat` in POSIX. + ;;; Create a symbolic link. + ;;; Note: This is similar to `symlinkat` in POSIX. (@interface func (export "path_symlink") - ;; The contents of the symbolic link. + ;;; The contents of the symbolic link. (param $old_path string) (param $fd $fd_t) - ;; The destination path at which to create the symbolic link. + ;;; The destination path at which to create the symbolic link. (param $new_path string) (result $error $errno_t) ) - ;; Unlink a file. - ;; Return `EISDIR` if the path refers to a directory. - ;; Note: This is similar to `unlinkat(fd, path, 0)` in POSIX. + ;;; Unlink a file. + ;;; Return `EISDIR` if the path refers to a directory. + ;;; Note: This is similar to `unlinkat(fd, path, 0)` in POSIX. (@interface func (export "path_unlink_file") (param $fd $fd_t) - ;; The path to a file to unlink. + ;;; The path to a file to unlink. (param $path string) (result $error $errno_t) ) - ;; Concurrently poll for the occurrence of a set of events. + ;;; Concurrently poll for the occurrence of a set of events. (@interface func (export "poll_oneoff") - ;; The events to which to subscribe. + ;;; The events to which to subscribe. (param $in (@witx const_pointer $subscription_t)) - ;; The events that have occurred. + ;;; The events that have occurred. (param $out (@witx pointer $event_t)) - ;; Both the number of subscriptions and events. + ;;; Both the number of subscriptions and events. (param $nsubscriptions $size_t) (result $error $errno_t) - ;; The number of events stored. + ;;; The number of events stored. (result $nevents $size_t) ) - ;; Terminate the process normally. An exit code of 0 indicates successful - ;; termination of the program. The meanings of other values is dependent on - ;; the environment. + ;;; Terminate the process normally. An exit code of 0 indicates successful + ;;; termination of the program. The meanings of other values is dependent on + ;;; the environment. (@interface func (export "proc_exit") - ;; The exit code returned by the process. + ;;; The exit code returned by the process. (param $rval $exitcode_t) ) - ;; Send a signal to the process of the calling thread. - ;; Note: This is similar to `raise` in POSIX. + ;;; Send a signal to the process of the calling thread. + ;;; Note: This is similar to `raise` in POSIX. (@interface func (export "proc_raise") - ;; The signal condition to trigger. + ;;; The signal condition to trigger. (param $sig $signal_t) (result $error $errno_t) ) - ;; Temporarily yield execution of the calling thread. - ;; Note: This is similar to `sched_yield` in POSIX. + ;;; Temporarily yield execution of the calling thread. + ;;; Note: This is similar to `sched_yield` in POSIX. (@interface func (export "sched_yield") (result $error $errno_t) ) - ;; Write high-quality random data into a buffer. - ;; This function blocks when the implementation is unable to immediately - ;; provide sufficient high-quality random data. - ;; This function may execute slowly, so when large mounts of random data are - ;; required, it's advisable to use this function to seed a pseudo-random - ;; number generator, rather than to provide the random data directly. + ;;; Write high-quality random data into a buffer. + ;;; This function blocks when the implementation is unable to immediately + ;;; provide sufficient high-quality random data. + ;;; This function may execute slowly, so when large mounts of random data are + ;;; required, it's advisable to use this function to seed a pseudo-random + ;;; number generator, rather than to provide the random data directly. (@interface func (export "random_get") - ;; The buffer to fill with random data. + ;;; The buffer to fill with random data. (param $buf (@witx pointer u8)) (param $buf_len $size_t) (result $error $errno_t) ) - ;; Receive a message from a socket. - ;; Note: This is similar to `recv` in POSIX, though it also supports reading - ;; the data into multiple buffers in the manner of `readv`. + ;;; Receive a message from a socket. + ;;; Note: This is similar to `recv` in POSIX, though it also supports reading + ;;; the data into multiple buffers in the manner of `readv`. (@interface func (export "sock_recv") (param $fd $fd_t) - ;; List of scatter/gather vectors to which to store data. + ;;; List of scatter/gather vectors to which to store data. (param $ri_data $iovec_t_array) - ;; Message flags. + ;;; Message flags. (param $ri_flags $riflags_t) (result $error $errno_t) - ;; Number of bytes stored in ri_data. + ;;; Number of bytes stored in ri_data. (result $ro_datalen $size_t) - ;; Message flags. + ;;; Message flags. (result $ro_flags $roflags_t) ) - ;; Send a message on a socket. - ;; Note: This is similar to `send` in POSIX, though it also supports writing - ;; the data from multiple buffers in the manner of `writev`. + ;;; Send a message on a socket. + ;;; Note: This is similar to `send` in POSIX, though it also supports writing + ;;; the data from multiple buffers in the manner of `writev`. (@interface func (export "sock_send") (param $fd $fd_t) - ;; List of scatter/gather vectors to which to retrieve data + ;;; List of scatter/gather vectors to which to retrieve data (param $si_data $ciovec_t_array) - ;; Message flags. + ;;; Message flags. (param $si_flags $siflags_t) (result $error $errno_t) - ;; Number of bytes transmitted. + ;;; Number of bytes transmitted. (result $so_datalen $size_t) ) - ;; Shut down socket send and receive channels. - ;; Note: This is similar to `shutdown` in POSIX. + ;;; Shut down socket send and receive channels. + ;;; Note: This is similar to `shutdown` in POSIX. (@interface func (export "sock_shutdown") (param $fd $fd_t) - ;; Which channels on the socket to shut down. + ;;; Which channels on the socket to shut down. (param $how $sdflags_t) (result $error $errno_t) ) diff --git a/phases/old/snapshot_0/witx/typenames.witx b/phases/old/snapshot_0/witx/typenames.witx index 15b53af51..cf39a2deb 100644 --- a/phases/old/snapshot_0/witx/typenames.witx +++ b/phases/old/snapshot_0/witx/typenames.witx @@ -7,291 +7,291 @@ (typename $size_t u32) -;; Non-negative file size or length of a region within a file. +;;; Non-negative file size or length of a region within a file. (typename $filesize_t u64) -;; Timestamp in nanoseconds. +;;; Timestamp in nanoseconds. (typename $timestamp_t u64) -;; Identifiers for clocks. +;;; Identifiers for clocks. (typename $clockid_t (enum u32 - ;; The clock measuring real time. Time value zero corresponds with - ;; 1970-01-01T00:00:00Z. + ;;; The clock measuring real time. Time value zero corresponds with + ;;; 1970-01-01T00:00:00Z. $CLOCK_REALTIME - ;; The store-wide monotonic clock, which is defined as a clock measuring - ;; real time, whose value cannot be adjusted and which cannot have negative - ;; clock jumps. The epoch of this clock is undefined. The absolute time - ;; value of this clock therefore has no meaning. + ;;; The store-wide monotonic clock, which is defined as a clock measuring + ;;; real time, whose value cannot be adjusted and which cannot have negative + ;;; clock jumps. The epoch of this clock is undefined. The absolute time + ;;; value of this clock therefore has no meaning. $CLOCK_MONOTONIC - ;; The CPU-time clock associated with the current process. + ;;; The CPU-time clock associated with the current process. $CLOCK_PROCESS_CPUTIME_ID - ;; The CPU-time clock associated with the current thread. + ;;; The CPU-time clock associated with the current thread. $CLOCK_THREAD_CPUTIME_ID ) ) -;; Error codes returned by functions. -;; 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. +;;; Error codes returned by functions. +;;; 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. (typename $errno_t (enum u16 - ;; No error occurred. System call completed successfully. + ;;; No error occurred. System call completed successfully. $ESUCCESS - ;; Argument list too long. + ;;; Argument list too long. $E2BIG - ;; Permission denied. + ;;; Permission denied. $EACCES - ;; Address in use. + ;;; Address in use. $EADDRINUSE - ;; Address not available. + ;;; Address not available. $EADDRNOTAVAIL - ;; Address family not supported. + ;;; Address family not supported. $EAFNOSUPPORT - ;; Resource unavailable, or operation would block. + ;;; Resource unavailable, or operation would block. $EAGAIN - ;; Connection already in progress. + ;;; Connection already in progress. $EALREADY - ;; Bad file descriptor. + ;;; Bad file descriptor. $EBADF - ;; Bad message. + ;;; Bad message. $EBADMSG - ;; Device or resource busy. + ;;; Device or resource busy. $EBUSY - ;; Operation canceled. + ;;; Operation canceled. $ECANCELED - ;; No child processes. + ;;; No child processes. $ECHILD - ;; Connection aborted. + ;;; Connection aborted. $ECONNABORTED - ;; Connection refused. + ;;; Connection refused. $ECONNREFUSED - ;; Connection reset. + ;;; Connection reset. $ECONNRESET - ;; Resource deadlock would occur. + ;;; Resource deadlock would occur. $EDEADLK - ;; Destination address required. + ;;; Destination address required. $EDESTADDRREQ - ;; Mathematics argument out of domain of function. + ;;; Mathematics argument out of domain of function. $EDOM - ;; Reserved. + ;;; Reserved. $EDQUOT - ;; File exists. + ;;; File exists. $EEXIST - ;; Bad address. + ;;; Bad address. $EFAULT - ;; File too large. + ;;; File too large. $EFBIG - ;; Host is unreachable. + ;;; Host is unreachable. $EHOSTUNREACH - ;; Identifier removed. + ;;; Identifier removed. $EIDRM - ;; Illegal byte sequence. + ;;; Illegal byte sequence. $EILSEQ - ;; Operation in progress. + ;;; Operation in progress. $EINPROGRESS - ;; Interrupted function. + ;;; Interrupted function. $EINTR - ;; Invalid argument. + ;;; Invalid argument. $EINVAL - ;; I/O error. + ;;; I/O error. $EIO - ;; Socket is connected. + ;;; Socket is connected. $EISCONN - ;; Is a directory. + ;;; Is a directory. $EISDIR - ;; Too many levels of symbolic links. + ;;; Too many levels of symbolic links. $ELOOP - ;; File descriptor value too large. + ;;; File descriptor value too large. $EMFILE - ;; Too many links. + ;;; Too many links. $EMLINK - ;; Message too large. + ;;; Message too large. $EMSGSIZE - ;; Reserved. + ;;; Reserved. $EMULTIHOP - ;; Filename too long. + ;;; Filename too long. $ENAMETOOLONG - ;; Network is down. + ;;; Network is down. $ENETDOWN - ;; Connection aborted by network. + ;;; Connection aborted by network. $ENETRESET - ;; Network unreachable. + ;;; Network unreachable. $ENETUNREACH - ;; Too many files open in system. + ;;; Too many files open in system. $ENFILE - ;; No buffer space available. + ;;; No buffer space available. $ENOBUFS - ;; No such device. + ;;; No such device. $ENODEV - ;; No such file or directory. + ;;; No such file or directory. $ENOENT - ;; Executable file format error. + ;;; Executable file format error. $ENOEXEC - ;; No locks available. + ;;; No locks available. $ENOLCK - ;; Reserved. + ;;; Reserved. $ENOLINK - ;; Not enough space. + ;;; Not enough space. $ENOMEM - ;; No message of the desired type. + ;;; No message of the desired type. $ENOMSG - ;; Protocol not available. + ;;; Protocol not available. $ENOPROTOOPT - ;; No space left on device. + ;;; No space left on device. $ENOSPC - ;; Function not supported. + ;;; Function not supported. $ENOSYS - ;; The socket is not connected. + ;;; The socket is not connected. $ENOTCONN - ;; Not a directory or a symbolic link to a directory. + ;;; Not a directory or a symbolic link to a directory. $ENOTDIR - ;; Directory not empty. + ;;; Directory not empty. $ENOTEMPTY - ;; State not recoverable. + ;;; State not recoverable. $ENOTRECOVERABLE - ;; Not a socket. + ;;; Not a socket. $ENOTSOCK - ;; Not supported, or operation not supported on socket. + ;;; Not supported, or operation not supported on socket. $ENOTSUP - ;; Inappropriate I/O control operation. + ;;; Inappropriate I/O control operation. $ENOTTY - ;; No such device or address. + ;;; No such device or address. $ENXIO - ;; Value too large to be stored in data type. + ;;; Value too large to be stored in data type. $EOVERFLOW - ;; Previous owner died. + ;;; Previous owner died. $EOWNERDEAD - ;; Operation not permitted. + ;;; Operation not permitted. $EPERM - ;; Broken pipe. + ;;; Broken pipe. $EPIPE - ;; Protocol error. + ;;; Protocol error. $EPROTO - ;; Protocol not supported. + ;;; Protocol not supported. $EPROTONOSUPPORT - ;; Protocol wrong type for socket. + ;;; Protocol wrong type for socket. $EPROTOTYPE - ;; Result too large. + ;;; Result too large. $ERANGE - ;; Read-only file system. + ;;; Read-only file system. $EROFS - ;; Invalid seek. + ;;; Invalid seek. $ESPIPE - ;; No such process. + ;;; No such process. $ESRCH - ;; Reserved. + ;;; Reserved. $ESTALE - ;; Connection timed out. + ;;; Connection timed out. $ETIMEDOUT - ;; Text file busy. + ;;; Text file busy. $ETXTBSY - ;; Cross-device link. + ;;; Cross-device link. $EXDEV - ;; Extension: Capabilities insufficient. + ;;; Extension: Capabilities insufficient. $ENOTCAPABLE ) ) -;; File descriptor rights, determining which actions may be performed. +;;; File descriptor rights, determining which actions may be performed. (typename $rights_t (flags u64 - ;; The right to invoke `fd_datasync`. + ;;; The right to invoke `fd_datasync`. ;; - ;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke - ;; `path_open` with `FDFLAG_DSYNC`. + ;;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke + ;;; `path_open` with `FDFLAG_DSYNC`. $RIGHT_FD_DATASYNC - ;; The right to invoke `fd_read` and `sock_recv`. + ;;; The right to invoke `fd_read` and `sock_recv`. ;; - ;; If `RIGHT_FD_SEEK` is set, includes the right to invoke `fd_pread`. + ;;; If `RIGHT_FD_SEEK` is set, includes the right to invoke `fd_pread`. $RIGHT_FD_READ - ;; The right to invoke `fd_seek`. This flag implies `RIGHT_FD_TELL`. + ;;; The right to invoke `fd_seek`. This flag implies `RIGHT_FD_TELL`. $RIGHT_FD_SEEK - ;; The right to invoke `fd_fdstat_set_flags`. + ;;; The right to invoke `fd_fdstat_set_flags`. $RIGHT_FD_FDSTAT_SET_FLAGS - ;; The right to invoke `fd_sync`. + ;;; The right to invoke `fd_sync`. ;; - ;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke - ;; `path_open` with `FDFLAG_RSYNC` and `FDFLAG_DSYNC`. + ;;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke + ;;; `path_open` with `FDFLAG_RSYNC` and `FDFLAG_DSYNC`. $RIGHT_FD_SYNC - ;; The right to invoke `fd_seek` in such a way that the file offset - ;; remains unaltered (i.e., `WHENCE_CUR` with offset zero), or to - ;; invoke `fd_tell`. + ;;; The right to invoke `fd_seek` in such a way that the file offset + ;;; remains unaltered (i.e., `WHENCE_CUR` with offset zero), or to + ;;; invoke `fd_tell`. $RIGHT_FD_TELL - ;; The right to invoke `fd_write` and `sock_send`. - ;; If `RIGHT_FD_SEEK` is set, includes the right to invoke `fd_pwrite`. + ;;; The right to invoke `fd_write` and `sock_send`. + ;;; If `RIGHT_FD_SEEK` is set, includes the right to invoke `fd_pwrite`. $RIGHT_FD_WRITE - ;; The right to invoke `fd_advise`. + ;;; The right to invoke `fd_advise`. $RIGHT_FD_ADVISE - ;; The right to invoke `fd_allocate`. + ;;; The right to invoke `fd_allocate`. $RIGHT_FD_ALLOCATE - ;; The right to invoke `path_create_directory`. + ;;; The right to invoke `path_create_directory`. $RIGHT_PATH_CREATE_DIRECTORY - ;; If `RIGHT_PATH_OPEN` is set, the right to invoke `path_open` with `O_CREAT`. + ;;; If `RIGHT_PATH_OPEN` is set, the right to invoke `path_open` with `O_CREAT`. $RIGHT_PATH_CREATE_FILE - ;; The right to invoke `path_link` with the file descriptor as the - ;; source directory. + ;;; The right to invoke `path_link` with the file descriptor as the + ;;; source directory. $RIGHT_PATH_LINK_SOURCE - ;; The right to invoke `path_link` with the file descriptor as the - ;; target directory. + ;;; The right to invoke `path_link` with the file descriptor as the + ;;; target directory. $RIGHT_PATH_LINK_TARGET - ;; The right to invoke `path_open`. + ;;; The right to invoke `path_open`. $RIGHT_PATH_OPEN - ;; The right to invoke `fd_readdir`. + ;;; The right to invoke `fd_readdir`. $RIGHT_FD_READDIR - ;; The right to invoke `path_readlink`. + ;;; The right to invoke `path_readlink`. $RIGHT_PATH_READLINK - ;; The right to invoke `path_rename` with the file descriptor as the source directory. + ;;; The right to invoke `path_rename` with the file descriptor as the source directory. $RIGHT_PATH_RENAME_SOURCE - ;; The right to invoke `path_rename` with the file descriptor as the target directory. + ;;; The right to invoke `path_rename` with the file descriptor as the target directory. $RIGHT_PATH_RENAME_TARGET - ;; The right to invoke `path_filestat_get`. + ;;; The right to invoke `path_filestat_get`. $RIGHT_PATH_FILESTAT_GET - ;; The right to change a file's size (there is no `path_filestat_set_size`). - ;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke `path_open` with `O_TRUNC`. + ;;; The right to change a file's size (there is no `path_filestat_set_size`). + ;;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke `path_open` with `O_TRUNC`. $RIGHT_PATH_FILESTAT_SET_SIZE - ;; The right to invoke `path_filestat_set_times`. + ;;; The right to invoke `path_filestat_set_times`. $RIGHT_PATH_FILESTAT_SET_TIMES - ;; The right to invoke `fd_filestat_get`. + ;;; The right to invoke `fd_filestat_get`. $RIGHT_FD_FILESTAT_GET - ;; The right to invoke `fd_filestat_set_size`. + ;;; The right to invoke `fd_filestat_set_size`. $RIGHT_FD_FILESTAT_SET_SIZE - ;; The right to invoke `fd_filestat_set_times`. + ;;; The right to invoke `fd_filestat_set_times`. $RIGHT_FD_FILESTAT_SET_TIMES - ;; The right to invoke `path_symlink`. + ;;; The right to invoke `path_symlink`. $RIGHT_PATH_SYMLINK - ;; The right to invoke `path_remove_directory`. + ;;; The right to invoke `path_remove_directory`. $RIGHT_PATH_REMOVE_DIRECTORY - ;; The right to invoke `path_unlink_file`. + ;;; The right to invoke `path_unlink_file`. $RIGHT_PATH_UNLINK_FILE - ;; If `RIGHT_FD_READ` is set, includes the right to invoke `poll_oneoff` to subscribe to `EVENTTYPE_FD_READ`. - ;; If `RIGHT_FD_WRITE` is set, includes the right to invoke `poll_oneoff` to subscribe to `EVENTTYPE_FD_WRITE`. + ;;; If `RIGHT_FD_READ` is set, includes the right to invoke `poll_oneoff` to subscribe to `EVENTTYPE_FD_READ`. + ;;; If `RIGHT_FD_WRITE` is set, includes the right to invoke `poll_oneoff` to subscribe to `EVENTTYPE_FD_WRITE`. $RIGHT_POLL_FD_READWRITE - ;; The right to invoke `sock_shutdown`. + ;;; The right to invoke `sock_shutdown`. $RIGHT_SOCK_SHUTDOWN ) ) -;; A file descriptor index. +;;; A file descriptor index. (typename $fd_t u32) -;; A region of memory for scatter/gather reads. +;;; A region of memory for scatter/gather reads. (typename $iovec_t (struct - ;; The address of the buffer to be filled. + ;;; The address of the buffer to be filled. (field $buf (@witx pointer u8)) - ;; The length of the buffer to be filled. + ;;; The length of the buffer to be filled. (field $buf_len $size_t) ) ) -;; A region of memory for scatter/gather writes. +;;; A region of memory for scatter/gather writes. (typename $ciovec_t (struct - ;; The address of the buffer to be written. + ;;; The address of the buffer to be written. (field $buf (@witx const_pointer u8)) - ;; The length of the buffer to be written. + ;;; The length of the buffer to be written. (field $buf_len $size_t) ) ) @@ -299,469 +299,469 @@ (typename $iovec_t_array (array $iovec_t)) (typename $ciovec_t_array (array $ciovec_t)) -;; Relative offset within a file. +;;; Relative offset within a file. (typename $filedelta_t s64) -;; The position relative to which to set the offset of the file descriptor. +;;; The position relative to which to set the offset of the file descriptor. (typename $whence_t (enum u8 - ;; Seek relative to current position. + ;;; Seek relative to current position. $WHENCE_CUR - ;; Seek relative to end-of-file. + ;;; Seek relative to end-of-file. $WHENCE_END - ;; Seek relative to start-of-file. + ;;; Seek relative to start-of-file. $WHENCE_SET ) ) -;; A reference to the offset of a directory entry. +;;; A reference to the offset of a directory entry. (typename $dircookie_t u64) -;; The type for the $d_namlen field of $dirent_t. +;;; The type for the $d_namlen field of $dirent_t. (typename $dirnamlen_t u32) -;; File serial number that is unique within its file system. +;;; File serial number that is unique within its file system. (typename $inode_t u64) -;; The type of a file descriptor or file. +;;; The type of a file descriptor or file. (typename $filetype_t (enum u8 - ;; The type of the file descriptor or file is unknown or is different from any of the other types specified. + ;;; The type of the file descriptor or file is unknown or is different from any of the other types specified. $FILETYPE_UNKNOWN - ;; The file descriptor or file refers to a block device inode. + ;;; The file descriptor or file refers to a block device inode. $FILETYPE_BLOCK_DEVICE - ;; The file descriptor or file refers to a character device inode. + ;;; The file descriptor or file refers to a character device inode. $FILETYPE_CHARACTER_DEVICE - ;; The file descriptor or file refers to a directory inode. + ;;; The file descriptor or file refers to a directory inode. $FILETYPE_DIRECTORY - ;; The file descriptor or file refers to a regular file inode. + ;;; The file descriptor or file refers to a regular file inode. $FILETYPE_REGULAR_FILE - ;; The file descriptor or file refers to a datagram socket. + ;;; The file descriptor or file refers to a datagram socket. $FILETYPE_SOCKET_DGRAM - ;; The file descriptor or file refers to a byte-stream socket. + ;;; The file descriptor or file refers to a byte-stream socket. $FILETYPE_SOCKET_STREAM - ;; The file refers to a symbolic link inode. + ;;; The file refers to a symbolic link inode. $FILETYPE_SYMBOLIC_LINK ) ) -;; A directory entry. +;;; A directory entry. (typename $dirent_t (struct - ;; The offset of the next directory entry stored in this directory. + ;;; The offset of the next directory entry stored in this directory. (field $d_next $dircookie_t) - ;; The serial number of the file referred to by this directory entry. + ;;; The serial number of the file referred to by this directory entry. (field $d_ino $inode_t) - ;; The length of the name of the directory entry. + ;;; The length of the name of the directory entry. (field $d_namlen $dirnamlen_t) - ;; The type of the file referred to by this directory entry. + ;;; The type of the file referred to by this directory entry. (field $d_type $filetype_t) ) ) -;; File or memory access pattern advisory information. +;;; File or memory access pattern advisory information. (typename $advice_t (enum u8 - ;; The application has no advice to give on its behavior with respect to the specified data. + ;;; The application has no advice to give on its behavior with respect to the specified data. $ADVICE_NORMAL - ;; The application expects to access the specified data sequentially from lower offsets to higher offsets. + ;;; The application expects to access the specified data sequentially from lower offsets to higher offsets. $ADVICE_SEQUENTIAL - ;; The application expects to access the specified data in a random order. + ;;; The application expects to access the specified data in a random order. $ADVICE_RANDOM - ;; The application expects to access the specified data in the near future. + ;;; The application expects to access the specified data in the near future. $ADVICE_WILLNEED - ;; The application expects that it will not access the specified data in the near future. + ;;; The application expects that it will not access the specified data in the near future. $ADVICE_DONTNEED - ;; The application expects to access the specified data once and then not reuse it thereafter. + ;;; The application expects to access the specified data once and then not reuse it thereafter. $ADVICE_NOREUSE ) ) -;; File descriptor flags. +;;; File descriptor flags. (typename $fdflags_t (flags u16 - ;; Append mode: Data written to the file is always appended to the file's end. + ;;; Append mode: Data written to the file is always appended to the file's end. $FDFLAG_APPEND - ;; Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized. + ;;; Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized. $FDFLAG_DSYNC - ;; Non-blocking mode. + ;;; Non-blocking mode. $FDFLAG_NONBLOCK - ;; Synchronized read I/O operations. + ;;; Synchronized read I/O operations. $FDFLAG_RSYNC - ;; Write according to synchronized I/O file integrity completion. In - ;; addition to synchronizing the data stored in the file, the implementation - ;; may also synchronously update the file's metadata. + ;;; Write according to synchronized I/O file integrity completion. In + ;;; addition to synchronizing the data stored in the file, the implementation + ;;; may also synchronously update the file's metadata. $FDFLAG_SYNC ) ) -;; File descriptor attributes. +;;; File descriptor attributes. (typename $fdstat_t (struct - ;; File type. + ;;; File type. (field $fs_filetype $filetype_t) - ;; File descriptor flags. + ;;; File descriptor flags. (field $fs_flags $fdflags_t) - ;; Rights that apply to this file descriptor. + ;;; Rights that apply to this file descriptor. (field $fs_rights_base $rights_t) - ;; Maximum set of rights that may be installed on new file descriptors that - ;; are created through this file descriptor, e.g., through `path_open`. + ;;; Maximum set of rights that may be installed on new file descriptors that + ;;; are created through this file descriptor, e.g., through `path_open`. (field $fs_rights_inheriting $rights_t) ) ) -;; Identifier for a device containing a file system. Can be used in combination -;; with `inode_t` to uniquely identify a file or directory in the filesystem. +;;; Identifier for a device containing a file system. Can be used in combination +;;; with `inode_t` to uniquely identify a file or directory in the filesystem. (typename $device_t u64) -;; Which file time attributes to adjust. +;;; Which file time attributes to adjust. (typename $fstflags_t (flags u16 - ;; Adjust the last data access timestamp to the value stored in `filestat_t::st_atim`. + ;;; Adjust the last data access timestamp to the value stored in `filestat_t::st_atim`. $FILESTAT_SET_ATIM - ;; Adjust the last data access timestamp to the time of clock `CLOCK_REALTIME`. + ;;; Adjust the last data access timestamp to the time of clock `CLOCK_REALTIME`. $FILESTAT_SET_ATIM_NOW - ;; Adjust the last data modification timestamp to the value stored in `filestat_t::st_mtim`. + ;;; Adjust the last data modification timestamp to the value stored in `filestat_t::st_mtim`. $FILESTAT_SET_MTIM - ;; Adjust the last data modification timestamp to the time of clock `CLOCK_REALTIME`. + ;;; Adjust the last data modification timestamp to the time of clock `CLOCK_REALTIME`. $FILESTAT_SET_MTIM_NOW ) ) -;; Flags determining the method of how paths are resolved. +;;; Flags determining the method of how paths are resolved. (typename $lookupflags_t (flags u32 - ;; As long as the resolved path corresponds to a symbolic link, it is expanded. + ;;; As long as the resolved path corresponds to a symbolic link, it is expanded. $LOOKUP_SYMLINK_FOLLOW ) ) -;; Open flags used by `path_open`. +;;; Open flags used by `path_open`. (typename $oflags_t (flags u16 - ;; Create file if it does not exist. + ;;; Create file if it does not exist. $O_CREAT - ;; Fail if not a directory. + ;;; Fail if not a directory. $O_DIRECTORY - ;; Fail if file already exists. + ;;; Fail if file already exists. $O_EXCL - ;; Truncate file to size 0. + ;;; Truncate file to size 0. $O_TRUNC ) ) -;; Number of hard links to an inode. +;;; Number of hard links to an inode. (typename $linkcount_t u32) -;; File attributes. +;;; File attributes. (typename $filestat_t (struct - ;; Device ID of device containing the file. + ;;; Device ID of device containing the file. (field $st_dev $device_t) - ;; File serial number. + ;;; File serial number. (field $st_ino $inode_t) - ;; File type. + ;;; File type. (field $st_filetype $filetype_t) - ;; Number of hard links to the file. + ;;; Number of hard links to the file. (field $st_nlink $linkcount_t) - ;; For regular files, the file size in bytes. For symbolic links, the length in bytes of the pathname contained in the symbolic link. + ;;; For regular files, the file size in bytes. For symbolic links, the length in bytes of the pathname contained in the symbolic link. (field $st_size $filesize_t) - ;; Last data access timestamp. + ;;; Last data access timestamp. (field $st_atim $timestamp_t) - ;; Last data modification timestamp. + ;;; Last data modification timestamp. (field $st_mtim $timestamp_t) - ;; Last file status change timestamp. + ;;; Last file status change timestamp. (field $st_ctim $timestamp_t) ) ) -;; User-provided value that may be attached to objects that is retained when -;; extracted from the implementation. +;;; User-provided value that may be attached to objects that is retained when +;;; extracted from the implementation. (typename $userdata_t u64) -;; Type of a subscription to an event or its occurrence. +;;; Type of a subscription to an event or its occurrence. (typename $eventtype_t (enum u8 - ;; The time value of clock `subscription_t::u.clock.clock_id` has - ;; reached timestamp `subscription_t::u.clock.timeout`. + ;;; The time value of clock `subscription_t::u.clock.clock_id` has + ;;; reached timestamp `subscription_t::u.clock.timeout`. $EVENTTYPE_CLOCK - ;; File descriptor `subscription_t::u.fd_readwrite.fd` has data - ;; available for reading. This event always triggers for regular files. + ;;; File descriptor `subscription_t::u.fd_readwrite.fd` has data + ;;; available for reading. This event always triggers for regular files. $EVENTTYPE_FD_READ - ;; File descriptor `subscription_t::u.fd_readwrite.fd` has capacity - ;; available for writing. This event always triggers for regular files. + ;;; File descriptor `subscription_t::u.fd_readwrite.fd` has capacity + ;;; available for writing. This event always triggers for regular files. $EVENTTYPE_FD_WRITE ) ) -;; The state of the file descriptor subscribed to with -;; `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`. +;;; The state of the file descriptor subscribed to with +;;; `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`. (typename $eventrwflags_t (flags u16 - ;; The peer of this socket has closed or disconnected. + ;;; The peer of this socket has closed or disconnected. $EVENT_FD_READWRITE_HANGUP ) ) -;; The contents of an $event_t when type is `EVENTTYPE_FD_READ` or -;; `EVENTTYPE_FD_WRITE`. +;;; The contents of an $event_t when type is `EVENTTYPE_FD_READ` or +;;; `EVENTTYPE_FD_WRITE`. (typename $event_fd_readwrite_t (struct - ;; The number of bytes available for reading or writing. + ;;; The number of bytes available for reading or writing. (field $nbytes $filesize_t) - ;; The state of the file descriptor. + ;;; The state of the file descriptor. (field $flags $eventrwflags_t) ) ) -;; The contents of an $event_t. +;;; The contents of an $event_t. (typename $event_u (union - ;; When type is `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`: + ;;; When type is `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`: (field $fd_readwrite $event_fd_readwrite_t) ) ) -;; An event that occurred. +;;; An event that occurred. (typename $event_t (struct - ;; User-provided value that got attached to `subscription_t::userdata`. + ;;; User-provided value that got attached to `subscription_t::userdata`. (field $userdata $userdata_t) - ;; If non-zero, an error that occurred while processing the subscription request. + ;;; If non-zero, an error that occurred while processing the subscription request. (field $error $errno_t) - ;; The type of the event that occurred. + ;;; The type of the event that occurred. (field $type $eventtype_t) - ;; The contents of the event. + ;;; The contents of the event. (field $u $event_u) ) ) -;; Flags determining how to interpret the timestamp provided in -;; `subscription_t::u.clock.timeout.` +;;; Flags determining how to interpret the timestamp provided in +;;; `subscription_t::u.clock.timeout.` (typename $subclockflags_t (flags u16 - ;; If set, treat the timestamp provided in - ;; `subscription_t::u.clock.timeout` as an absolute timestamp of clock - ;; `subscription_t::u.clock.clock_id.` If clear, treat the timestamp - ;; provided in `subscription_t::u.clock.timeout` relative to the - ;; current time value of clock `subscription_t::u.clock.clock_id.` + ;;; If set, treat the timestamp provided in + ;;; `subscription_t::u.clock.timeout` as an absolute timestamp of clock + ;;; `subscription_t::u.clock.clock_id.` If clear, treat the timestamp + ;;; provided in `subscription_t::u.clock.timeout` relative to the + ;;; current time value of clock `subscription_t::u.clock.clock_id.` $SUBSCRIPTION_CLOCK_ABSTIME ) ) -;; The contents of a $subscription_t when type is `EVENTTYPE_CLOCK`. +;;; The contents of a $subscription_t when type is `EVENTTYPE_CLOCK`. (typename $subscription_clock_t (struct - ;; The user-defined unique identifier of the clock. + ;;; The user-defined unique identifier of the clock. (field $identifier $userdata_t) - ;; The clock against which to compare the timestamp. + ;;; The clock against which to compare the timestamp. (field $clock_id $clockid_t) - ;; The absolute or relative timestamp. + ;;; The absolute or relative timestamp. (field $timeout $timestamp_t) - ;; The amount of time that the implementation may wait additionally - ;; to coalesce with other events. + ;;; The amount of time that the implementation may wait additionally + ;;; to coalesce with other events. (field $precision $timestamp_t) - ;; Flags specifying whether the timeout is absolute or relative + ;;; Flags specifying whether the timeout is absolute or relative (field $flags $subclockflags_t) ) ) -;; The contents of a $subscription_t when type is type is -;; `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`. +;;; The contents of a $subscription_t when type is type is +;;; `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`. (typename $subscription_fd_readwrite_t (struct - ;; The file descriptor on which to wait for it to become ready for reading or writing. + ;;; The file descriptor on which to wait for it to become ready for reading or writing. (field $file_descriptor $fd_t) ) ) -;; The contents of a $subscription_t. +;;; The contents of a $subscription_t. (typename $subscription_u (union - ;; When type is `EVENTTYPE_CLOCK`: + ;;; When type is `EVENTTYPE_CLOCK`: (field $clock $subscription_clock_t) - ;; When type is `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`: + ;;; When type is `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`: (field $fd_readwrite $subscription_fd_readwrite_t) ) ) -;; Subscription to an event. +;;; Subscription to an event. (typename $subscription_t (struct - ;; User-provided value that is attached to the subscription in the - ;; implementation and returned through `event_t::userdata`. + ;;; User-provided value that is attached to the subscription in the + ;;; implementation and returned through `event_t::userdata`. (field $userdata $userdata_t) - ;; The type of the event to which to subscribe. + ;;; The type of the event to which to subscribe. (field $type $eventtype_t) - ;; The contents of the subscription. + ;;; The contents of the subscription. (field $u $subscription_u) ) ) -;; Exit code generated by a process when exiting. +;;; Exit code generated by a process when exiting. (typename $exitcode_t u32) -;; Signal condition. +;;; Signal condition. (typename $signal_t (enum u8 - ;; No signal. Note that POSIX has special semantics for `kill(pid, 0)`, - ;; so this value is reserved. + ;;; No signal. Note that POSIX has special semantics for `kill(pid, 0)`, + ;;; so this value is reserved. $SIGNONE - ;; Hangup. - ;; Action: Terminates the process. + ;;; Hangup. + ;;; Action: Terminates the process. $SIGHUP - ;; Terminate interrupt signal. - ;; Action: Terminates the process. + ;;; Terminate interrupt signal. + ;;; Action: Terminates the process. $SIGINT - ;; Terminal quit signal. - ;; Action: Terminates the process. + ;;; Terminal quit signal. + ;;; Action: Terminates the process. $SIGQUIT - ;; Illegal instruction. - ;; Action: Terminates the process. + ;;; Illegal instruction. + ;;; Action: Terminates the process. $SIGILL - ;; Trace/breakpoint trap. - ;; Action: Terminates the process. + ;;; Trace/breakpoint trap. + ;;; Action: Terminates the process. $SIGTRAP - ;; Process abort signal. - ;; Action: Terminates the process. + ;;; Process abort signal. + ;;; Action: Terminates the process. $SIGABRT - ;; Access to an undefined portion of a memory object. - ;; Action: Terminates the process. + ;;; Access to an undefined portion of a memory object. + ;;; Action: Terminates the process. $SIGBUS - ;; Erroneous arithmetic operation. - ;; Action: Terminates the process. + ;;; Erroneous arithmetic operation. + ;;; Action: Terminates the process. $SIGFPE - ;; Kill. - ;; Action: Terminates the process. + ;;; Kill. + ;;; Action: Terminates the process. $SIGKILL - ;; User-defined signal 1. - ;; Action: Terminates the process. + ;;; User-defined signal 1. + ;;; Action: Terminates the process. $SIGUSR1 - ;; Invalid memory reference. - ;; Action: Terminates the process. + ;;; Invalid memory reference. + ;;; Action: Terminates the process. $SIGSEGV - ;; User-defined signal 2. - ;; Action: Terminates the process. + ;;; User-defined signal 2. + ;;; Action: Terminates the process. $SIGUSR2 - ;; Write on a pipe with no one to read it. - ;; Action: Ignored. + ;;; Write on a pipe with no one to read it. + ;;; Action: Ignored. $SIGPIPE - ;; Alarm clock. - ;; Action: Terminates the process. + ;;; Alarm clock. + ;;; Action: Terminates the process. $SIGALRM - ;; Termination signal. - ;; Action: Terminates the process. + ;;; Termination signal. + ;;; Action: Terminates the process. $SIGTERM - ;; Child process terminated, stopped, or continued. - ;; Action: Ignored. + ;;; Child process terminated, stopped, or continued. + ;;; Action: Ignored. $SIGCHLD - ;; Continue executing, if stopped. - ;; Action: Continues executing, if stopped. + ;;; Continue executing, if stopped. + ;;; Action: Continues executing, if stopped. $SIGCONT - ;; Stop executing. - ;; Action: Stops executing. + ;;; Stop executing. + ;;; Action: Stops executing. $SIGSTOP - ;; Terminal stop signal. - ;; Action: Stops executing. + ;;; Terminal stop signal. + ;;; Action: Stops executing. $SIGTSTP - ;; Background process attempting read. - ;; Action: Stops executing. + ;;; Background process attempting read. + ;;; Action: Stops executing. $SIGTTIN - ;; Background process attempting write. - ;; Action: Stops executing. + ;;; Background process attempting write. + ;;; Action: Stops executing. $SIGTTOU - ;; High bandwidth data is available at a socket. - ;; Action: Ignored. + ;;; High bandwidth data is available at a socket. + ;;; Action: Ignored. $SIGURG - ;; CPU time limit exceeded. - ;; Action: Terminates the process. + ;;; CPU time limit exceeded. + ;;; Action: Terminates the process. $SIGXCPU - ;; File size limit exceeded. - ;; Action: Terminates the process. + ;;; File size limit exceeded. + ;;; Action: Terminates the process. $SIGXFSZ - ;; Virtual timer expired. - ;; Action: Terminates the process. + ;;; Virtual timer expired. + ;;; Action: Terminates the process. $SIGVTALRM - ;; Profiling timer expired. - ;; Action: Terminates the process. + ;;; Profiling timer expired. + ;;; Action: Terminates the process. $SIGPROF - ;; Window changed. - ;; Action: Ignored. + ;;; Window changed. + ;;; Action: Ignored. $SIGWINCH - ;; I/O possible. - ;; Action: Terminates the process. + ;;; I/O possible. + ;;; Action: Terminates the process. $SIGPOLL - ;; Power failure. - ;; Action: Terminates the process. + ;;; Power failure. + ;;; Action: Terminates the process. $SIGPWR - ;; Bad system call. - ;; Action: Terminates the process. + ;;; Bad system call. + ;;; Action: Terminates the process. $SIGSYS ) ) -;; Flags provided to `sock_recv`. +;;; Flags provided to `sock_recv`. (typename $riflags_t (flags u16 - ;; Returns the message without removing it from the socket's receive queue. + ;;; Returns the message without removing it from the socket's receive queue. $SOCK_RECV_PEEK - ;; On byte-stream sockets, block until the full amount of data can be returned. + ;;; On byte-stream sockets, block until the full amount of data can be returned. $SOCK_RECV_WAITALL ) ) -;; Flags returned by `sock_recv`. +;;; Flags returned by `sock_recv`. (typename $roflags_t (flags u16 - ;; Returned by `sock_recv`: Message data has been truncated. + ;;; Returned by `sock_recv`: Message data has been truncated. $SOCK_RECV_DATA_TRUNCATED ) ) -;; Flags provided to `sock_send`. As there are currently no flags -;; defined, it must be set to zero. +;;; Flags provided to `sock_send`. As there are currently no flags +;;; defined, it must be set to zero. (typename $siflags_t u16) -;; Which channels on a socket to shut down. +;;; Which channels on a socket to shut down. (typename $sdflags_t (flags u8 - ;; Disables further receive operations. + ;;; Disables further receive operations. $SHUT_RD - ;; Disables further send operations. + ;;; Disables further send operations. $SHUT_WR ) ) -;; Identifiers for preopened capabilities. +;;; Identifiers for preopened capabilities. (typename $preopentype_t (enum u8 - ;; A pre-opened directory. + ;;; A pre-opened directory. $PREOPENTYPE_DIR ) ) -;; The contents of a $prestat_t when type is `PREOPENTYPE_DIR`. +;;; The contents of a $prestat_t when type is `PREOPENTYPE_DIR`. (typename $prestat_dir (struct - ;; The length of the directory name for use with `fd_prestat_dir_name`. + ;;; The length of the directory name for use with `fd_prestat_dir_name`. (field $pr_name_len $size_t) ) ) -;; The contents of an $prestat_t. +;;; The contents of an $prestat_t. (typename $prestat_u (union - ;; When type is `PREOPENTYPE_DIR`: + ;;; When type is `PREOPENTYPE_DIR`: (field $dir $prestat_dir) ) ) -;; Information about a pre-opened capability. +;;; Information about a pre-opened capability. (typename $prestat_t (struct - ;; The type of the pre-opened capability. + ;;; The type of the pre-opened capability. (field $pr_type $preopentype_t) - ;; The contents of the information. + ;;; The contents of the information. (field $u $prestat_u) ) ) diff --git a/phases/old/snapshot_0/witx/wasi_unstable.witx b/phases/old/snapshot_0/witx/wasi_unstable.witx index 74bce70c6..4cf5f4ffa 100644 --- a/phases/old/snapshot_0/witx/wasi_unstable.witx +++ b/phases/old/snapshot_0/witx/wasi_unstable.witx @@ -8,523 +8,526 @@ (use "typenames.witx") -;; This API predated the convention of naming modules with a `wasi_unstable_` -;; prefix and a version number. It is preserved here for compatibility, but -;; we shouldn't follow this pattern in new APIs. +;;; This API predated the convention of naming modules with a `wasi_unstable_` +;;; prefix and a version number. It is preserved here for compatibility, but +;;; we shouldn't follow this pattern in new APIs. (module $wasi_unstable - ;; Linear memory to be accessed by WASI functions that need it. + ;;; Linear memory to be accessed by WASI functions that need it. (import "memory" (memory)) - ;; Read command-line argument data. - ;; The size of the array should match that returned by `wasi_args_sizes_get()` + ;;; Read command-line argument data. + ;;; The size of the array should match that returned by `wasi_args_sizes_get()` (@interface func (export "args_get") (param $argv (@witx pointer (@witx pointer u8))) (param $argv_buf (@witx pointer u8)) (result $error $errno_t) ) - ;; Return command-line argument data sizes. + ;;; Return command-line argument data sizes. (@interface func (export "args_sizes_get") (result $error $errno_t) - ;; The number of arguments. + ;;; The number of arguments. (result $argc $size_t) - ;; The size of the argument string data. + ;;; The size of the argument string data. (result $argv_buf_size $size_t) ) - ;; Read environment variable data. - ;; The sizes of the buffers should match that returned by `environ.sizes_get()`. + ;;; Read environment variable data. + ;;; The sizes of the buffers should match that returned by `environ.sizes_get()`. (@interface func (export "environ_get") (param $environ (@witx pointer (@witx pointer u8))) (param $environ_buf (@witx pointer u8)) (result $error $errno_t) ) - ;; Return command-line argument data sizes. + ;;; Return command-line argument data sizes. (@interface func (export "environ_sizes_get") (result $error $errno_t) - ;; The number of arguments. + ;;; The number of arguments. (result $argc $size_t) - ;; The size of the argument string data. + ;;; The size of the argument string data. (result $argv_buf_size $size_t) ) - ;; Return the resolution of a clock. - ;; Implementations are required to provide a non-zero value for supported clocks. For unsupported clocks, return `WASI_EINVAL` - ;; Note: This is similar to `clock_getres` in POSIX. + ;;; Return the resolution of a clock. + ;;; Implementations are required to provide a non-zero value for supported clocks. For unsupported clocks, return `WASI_EINVAL` + ;;; Note: This is similar to `clock_getres` in POSIX. (@interface func (export "clock_res_get") (result $error $errno_t) - ;; The clock for which to return the resolution. + ;;; The clock for which to return the resolution. (param $clock_id $clockid_t) - ;; The resolution of the clock. + ;;; The resolution of the clock. (result $resolution $timestamp_t) ) - ;; Return the time value of a clock. - ;; Note: This is similar to `clock_gettime` in POSIX. + ;;; Return the time value of a clock. + ;;; Note: This is similar to `clock_gettime` in POSIX. (@interface func (export "clock_time_get") - ;; The clock for which to return the time. + ;;; The clock for which to return the time. (param $clock_id $clockid_t) - ;; The maximum lag (exclusive) that the returned time value may have, compared to its actual value. + ;;; The maximum lag (exclusive) that the returned time value may have, compared to its actual value. (param $precision $timestamp_t) (result $error $errno_t) - ;; The time value of the clock. + ;;; The time value of the clock. (result $time $timestamp_t) ) - ;; Provide file advisory information on a file descriptor. - ;; Note: This is similar to `posix_fadvise` in POSIX. + ;;; Provide file advisory information on a file descriptor. + ;;; Note: This is similar to `posix_fadvise` in POSIX. (@interface func (export "fd_advise") (param $fd $fd_t) - (param $offset $filesize_t) ;; The offset within the file to which the advisory applies. - (param $len $filesize_t) ;; The length of the region to which the advisory applies. - (param $advice $advice_t) ;; The advice. + ;;; The offset within the file to which the advisory applies. + (param $offset $filesize_t) + ;;; The length of the region to which the advisory applies. + (param $len $filesize_t) + ;;; The advice. + (param $advice $advice_t) (result $error $errno_t) ) - ;; Force the allocation of space in a file. - ;; Note: This is similar to `posix_fallocate` in POSIX. + ;;; Force the allocation of space in a file. + ;;; Note: This is similar to `posix_fallocate` in POSIX. (@interface func (export "fd_allocate") (param $fd $fd_t) - ;; The offset at which to start the allocation. + ;;; The offset at which to start the allocation. (param $offset $filesize_t) - ;; The length of the area that is allocated. + ;;; The length of the area that is allocated. (param $len $filesize_t) (result $error $errno_t) ) - ;; Close a file descriptor. - ;; Note: This is similar to `close` in POSIX. + ;;; Close a file descriptor. + ;;; Note: This is similar to `close` in POSIX. (@interface func (export "fd_close") (param $fd $fd_t) (result $error $errno_t) ) - ;; Synchronize the data of a file to disk. - ;; Note: This is similar to `fdatasync` in POSIX. + ;;; Synchronize the data of a file to disk. + ;;; Note: This is similar to `fdatasync` in POSIX. (@interface func (export "fd_datasync") (param $fd $fd_t) (result $error $errno_t) ) - ;; Get the attributes of a file descriptor. - ;; Note: This returns similar flags to `fsync(fd, F_GETFL)` in POSIX, as well as additional fields. + ;;; Get the attributes of a file descriptor. + ;;; Note: This returns similar flags to `fsync(fd, F_GETFL)` in POSIX, as well as additional fields. (@interface func (export "fd_fdstat_get") (param $fd $fd_t) (result $error $errno_t) - ;; The buffer where the file descriptor's attributes are stored. + ;;; The buffer where the file descriptor's attributes are stored. (result $stat $fdstat_t) ) - ;; Adjust the flags associated with a file descriptor. - ;; Note: This is similar to `fcntl(fd, F_SETFL, flags)` in POSIX. + ;;; Adjust the flags associated with a file descriptor. + ;;; Note: This is similar to `fcntl(fd, F_SETFL, flags)` in POSIX. (@interface func (export "fd_fdstat_set_flags") (param $fd $fd_t) - ;; The desired values of the file descriptor flags. + ;;; The desired values of the file descriptor flags. (param $flags $fdflags_t) (result $error $errno_t) ) - ;; Adjust the rights associated with a file descriptor. - ;; This can only be used to remove rights, and returns `ENOTCAPABLE` if called in a way that would attempt to add rights + ;;; Adjust the rights associated with a file descriptor. + ;;; This can only be used to remove rights, and returns `ENOTCAPABLE` if called in a way that would attempt to add rights (@interface func (export "fd_fdstat_set_rights") (param $fd $fd_t) - ;; The desired rights of the file descriptor. + ;;; The desired rights of the file descriptor. (param $fs_rights_base $rights_t) (param $fs_rights_inheriting $rights_t) (result $error $errno_t) ) - ;; Return the attributes of an open file. + ;;; Return the attributes of an open file. (@interface func (export "fd_filestat_get") (param $fd $fd_t) (result $error $errno_t) - ;; The buffer where the file's attributes are stored. + ;;; The buffer where the file's attributes are stored. (result $buf $filestat_t) ) - ;; Adjust the size of an open file. If this increases the file's size, the extra bytes are filled with zeros. - ;; Note: This is similar to `ftruncate` in POSIX. + ;;; Adjust the size of an open file. If this increases the file's size, the extra bytes are filled with zeros. + ;;; Note: This is similar to `ftruncate` in POSIX. (@interface func (export "fd_filestat_set_size") (param $fd $fd_t) - ;; The desired file size. + ;;; The desired file size. (param $st_size $filesize_t) (result $error $errno_t) ) - ;; Adjust the timestamps of an open file or directory. - ;; Note: This is similar to `futimens` in POSIX. + ;;; Adjust the timestamps of an open file or directory. + ;;; Note: This is similar to `futimens` in POSIX. (@interface func (export "fd_filestat_set_times") (param $fd $fd_t) - ;; The desired values of the data access timestamp. + ;;; The desired values of the data access timestamp. (param $st_atim $timestamp_t) - ;; The desired values of the data modification timestamp. + ;;; The desired values of the data modification timestamp. (param $st_mtim $timestamp_t) - ;; A bitmask indicating which timestamps to adjust. + ;;; A bitmask indicating which timestamps to adjust. (param $fst_flags $fstflags_t) (result $error $errno_t) ) - ;; Read from a file descriptor, without using and updating the file descriptor's offset. - ;; Note: This is similar to `preadv` in POSIX. + ;;; Read from a file descriptor, without using and updating the file descriptor's offset. + ;;; Note: This is similar to `preadv` in POSIX. (@interface func (export "fd_pread") (param $fd $fd_t) - ;; List of scatter/gather vectors in which to store data. + ;;; List of scatter/gather vectors in which to store data. (param $iovs $iovec_t_array) - ;; The offset within the file at which to read. + ;;; The offset within the file at which to read. (param $offset $filesize_t) (result $error $errno_t) - ;; The number of bytes read. + ;;; The number of bytes read. (result $nread $size_t) ) - ;; Return a description of the given preopened file descriptor. + ;;; Return a description of the given preopened file descriptor. (@interface func (export "fd_prestat_get") (param $fd $fd_t) (result $error $errno_t) - ;; The buffer where the description is stored. + ;;; The buffer where the description is stored. (result $buf $prestat_t) ) - ;; Return a description of the given preopened file descriptor. + ;;; Return a description of the given preopened file descriptor. (@interface func (export "fd_prestat_dir_name") (param $fd $fd_t) - ;; A buffer into which to write the preopened directory name. + ;;; A buffer into which to write the preopened directory name. (param $path (@witx pointer u8)) (param $path_len $size_t) (result $error $errno_t) ) - ;; Write to a file descriptor, without using and updating the file descriptor's offset. - ;; Note: This is similar to `pwritev` in POSIX. + ;;; Write to a file descriptor, without using and updating the file descriptor's offset. + ;;; Note: This is similar to `pwritev` in POSIX. (@interface func (export "fd_pwrite") (param $fd $fd_t) - ;; List of scatter/gather vectors from which to retrieve data. + ;;; List of scatter/gather vectors from which to retrieve data. (param $iovs $ciovec_t_array) - ;; The offset within the file at which to write. + ;;; The offset within the file at which to write. (param $offset $filesize_t) (result $error $errno_t) - ;; The number of bytes written. + ;;; The number of bytes written. (result $nwritten $size_t) ) - ;; Read from a file descriptor. - ;; Note: This is similar to `readv` in POSIX. + ;;; Read from a file descriptor. + ;;; Note: This is similar to `readv` in POSIX. (@interface func (export "fd_read") (param $fd $fd_t) - ;; List of scatter/gather vectors to which to store data. + ;;; List of scatter/gather vectors to which to store data. (param $iovs $iovec_t_array) (result $error $errno_t) - ;; The number of bytes read. + ;;; The number of bytes read. (result $nread $size_t) ) - ;; Read directory entries from a directory. - ;; When successful, the contents of the output buffer consist of a sequence of - ;; directory entries. Each directory entry consists of a dirent_t object, - ;; followed by dirent_t::d_namlen bytes holding the name of the directory - ;; entry. + ;;; Read directory entries from a directory. + ;;; When successful, the contents of the output buffer consist of a sequence of + ;;; directory entries. Each directory entry consists of a dirent_t object, + ;;; followed by dirent_t::d_namlen bytes holding the name of the directory + ;;; entry. ;; - ;; This function fills the output buffer as much as possible, potentially - ;; truncating the last directory entry. This allows the caller to grow its - ;; read buffer size in case it's too small to fit a single large directory - ;; entry, or skip the oversized directory entry. + ;;; This function fills the output buffer as much as possible, potentially + ;;; truncating the last directory entry. This allows the caller to grow its + ;;; read buffer size in case it's too small to fit a single large directory + ;;; entry, or skip the oversized directory entry. (@interface func (export "fd_readdir") (param $fd $fd_t) - ;; The buffer where directory entries are stored + ;;; The buffer where directory entries are stored (param $buf (@witx pointer u8)) (param $buf_len $size_t) - ;; The location within the directory to start reading + ;;; The location within the directory to start reading (param $cookie $dircookie_t) (result $error $errno_t) - ;; The number of bytes stored in the read buffer. If less than the size of the read buffer, the end of the directory has been reached. + ;;; The number of bytes stored in the read buffer. If less than the size of the read buffer, the end of the directory has been reached. (result $bufused $size_t) ) - ;; Atomically replace a file descriptor by renumbering another file descriptor. + ;;; Atomically replace a file descriptor by renumbering another file descriptor. ;; - ;; Due to the strong focus on thread safety, this environment does not provide - ;; a mechanism to duplicate or renumber a file descriptor to an arbitrary - ;; number, like `dup2()`. This would be prone to race conditions, as an actual - ;; file descriptor with the same number could be allocated by a different - ;; thread at the same time. + ;;; Due to the strong focus on thread safety, this environment does not provide + ;;; a mechanism to duplicate or renumber a file descriptor to an arbitrary + ;;; number, like `dup2()`. This would be prone to race conditions, as an actual + ;;; file descriptor with the same number could be allocated by a different + ;;; thread at the same time. ;; - ;; This function provides a way to atomically renumber file descriptors, which - ;; would disappear if `dup2()` were to be removed entirely. + ;;; This function provides a way to atomically renumber file descriptors, which + ;;; would disappear if `dup2()` were to be removed entirely. (@interface func (export "fd_renumber") (param $fd $fd_t) - ;; The file descriptor to overwrite. + ;;; The file descriptor to overwrite. (param $to $fd_t) (result $error $errno_t) ) - ;; Move the offset of a file descriptor. - ;; Note: This is similar to `lseek` in POSIX. + ;;; Move the offset of a file descriptor. + ;;; Note: This is similar to `lseek` in POSIX. (@interface func (export "fd_seek") (param $fd $fd_t) - ;; The number of bytes to move. + ;;; The number of bytes to move. (param $offset $filedelta_t) - ;; The base from which the offset is relative. + ;;; The base from which the offset is relative. (param $whence $whence_t) (result $error $errno_t) - ;; The new offset of the file descriptor, relative to the start of the file. + ;;; The new offset of the file descriptor, relative to the start of the file. (result $newoffset $filesize_t) ) - ;; Synchronize the data and metadata of a file to disk. - ;; Note: This is similar to `fsync` in POSIX. + ;;; Synchronize the data and metadata of a file to disk. + ;;; Note: This is similar to `fsync` in POSIX. (@interface func (export "fd_sync") (param $fd $fd_t) (result $error $errno_t) ) - ;; Return the current offset of a file descriptor. - ;; Note: This is similar to `lseek(fd, 0, SEEK_CUR)` in POSIX. + ;;; Return the current offset of a file descriptor. + ;;; Note: This is similar to `lseek(fd, 0, SEEK_CUR)` in POSIX. (@interface func (export "fd_tell") (param $fd $fd_t) (result $error $errno_t) - ;; The current offset of the file descriptor, relative to the start of the file. + ;;; The current offset of the file descriptor, relative to the start of the file. (result $offset $filesize_t) ) - ;; Write to a file descriptor. - ;; Note: This is similar to `writev` in POSIX. + ;;; Write to a file descriptor. + ;;; Note: This is similar to `writev` in POSIX. (@interface func (export "fd_write") (param $fd $fd_t) - ;; List of scatter/gather vectors from which to retrieve data. + ;;; List of scatter/gather vectors from which to retrieve data. (param $iovs $ciovec_t_array) (result $error $errno_t) - ;; The number of bytes written. + ;;; The number of bytes written. (result $nwritten $size_t) ) - ;; Create a directory. - ;; Note: This is similar to `mkdirat` in POSIX. + ;;; Create a directory. + ;;; Note: This is similar to `mkdirat` in POSIX. (@interface func (export "path_create_directory") (param $fd $fd_t) - ;; The path at which to create the directory. + ;;; The path at which to create the directory. (param $path string) (result $error $errno_t) ) - ;; Return the attributes of a file or directory. - ;; Note: This is similar to `stat` in POSIX. + ;;; Return the attributes of a file or directory. + ;;; Note: This is similar to `stat` in POSIX. (@interface func (export "path_filestat_get") (param $fd $fd_t) - ;; Flags determining the method of how the path is resolved. + ;;; Flags determining the method of how the path is resolved. (param $flags $lookupflags_t) - ;; The path of the file or directory to inspect. + ;;; The path of the file or directory to inspect. (param $path string) (result $error $errno_t) - ;; The buffer where the file's attributes are stored. + ;;; The buffer where the file's attributes are stored. (result $buf $filestat_t) ) - ;; Adjust the timestamps of a file or directory. - ;; Note: This is similar to `utimensat` in POSIX. + ;;; Adjust the timestamps of a file or directory. + ;;; Note: This is similar to `utimensat` in POSIX. (@interface func (export "path_filestat_set_times") (param $fd $fd_t) - ;; Flags determining the method of how the path is resolved. + ;;; Flags determining the method of how the path is resolved. (param $flags $lookupflags_t) - ;; The path of the file or directory to operate on. + ;;; The path of the file or directory to operate on. (param $path string) - ;; The desired values of the data access timestamp. + ;;; The desired values of the data access timestamp. (param $st_atim $timestamp_t) - ;; The desired values of the data modification timestamp. + ;;; The desired values of the data modification timestamp. (param $st_mtim $timestamp_t) - ;; A bitmask indicating which timestamps to adjust. + ;;; A bitmask indicating which timestamps to adjust. (param $fst_flags $fstflags_t) (result $error $errno_t) ) - ;; Create a hard link. - ;; Note: This is similar to `linkat` in POSIX. + ;;; Create a hard link. + ;;; Note: This is similar to `linkat` in POSIX. (@interface func (export "path_link") (param $old_fd $fd_t) - ;; Flags determining the method of how the path is resolved. + ;;; Flags determining the method of how the path is resolved. (param $old_flags $lookupflags_t) - ;; The source path from which to link. + ;;; The source path from which to link. (param $old_path string) - ;; The working directory at which the resolution of the new path starts. + ;;; The working directory at which the resolution of the new path starts. (param $new_fd $fd_t) - ;; The destination path at which to create the hard link. + ;;; The destination path at which to create the hard link. (param $new_path string) (result $error $errno_t) ) - ;; Open a file or directory. + ;;; Open a file or directory. ;; - ;; The returned file descriptor is not guaranteed to be the lowest-numbered - ;; file 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 file descriptor is - ;; guaranteed to be less than 2**31. + ;;; The returned file descriptor is not guaranteed to be the lowest-numbered + ;;; file 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 file descriptor is + ;;; guaranteed to be less than 2**31. ;; - ;; Note: This is similar to `openat` in POSIX. + ;;; Note: This is similar to `openat` in POSIX. (@interface func (export "path_open") (param $fd $fd_t) - ;; Flags determining the method of how the path is resolved. + ;;; Flags determining the method of how the path is resolved. (param $dirflags $lookupflags_t) - ;; The relative path of the file or directory to open, relative to the - ;; `dirfd` directory. + ;;; The relative path of the file or directory to open, relative to the + ;;; `dirfd` directory. (param $path string) - ;; The method by which to open the file. + ;;; The method by which to open the file. (param $o_flags $oflags_t) - ;; The initial 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 initial 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 *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. (param $fs_rights_base $rights_t) (param $fs_rights_inherting $rights_t) (param $flags $fdflags_t) (result $error $errno_t) - ;; The file descriptor of the file that has been opened. + ;;; The file descriptor of the file that has been opened. (result $opened_fd $fd_t) ) - ;; Read the contents of a symbolic link. - ;; Note: This is similar to `readlinkat` in POSIX. + ;;; Read the contents of a symbolic link. + ;;; Note: This is similar to `readlinkat` in POSIX. (@interface func (export "path_readlink") (param $fd $fd_t) - ;; The path of the symbolic link from which to read. + ;;; The path of the symbolic link from which to read. (param $path string) - ;; The buffer to which to write the contents of the symbolic link. + ;;; The buffer to which to write the contents of the symbolic link. (param $buf (@witx pointer u8)) (param $buf_len $size_t) (result $error $errno_t) - ;; The number of bytes placed in the buffer. + ;;; The number of bytes placed in the buffer. (result $bufused $size_t) ) - ;; Remove a directory. - ;; Return `ENOTEMPTY` if the directory is not empty. - ;; Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX. + ;;; Remove a directory. + ;;; Return `ENOTEMPTY` if the directory is not empty. + ;;; Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX. (@interface func (export "path_remove_directory") (param $fd $fd_t) - ;; The path to a directory to remove. + ;;; The path to a directory to remove. (param $path string) (result $error $errno_t) ) - ;; Rename a file or directory. - ;; Note: This is similar to `renameat` in POSIX. + ;;; Rename a file or directory. + ;;; Note: This is similar to `renameat` in POSIX. (@interface func (export "path_rename") (param $fd $fd_t) - ;; The source path of the file or directory to rename. + ;;; The source path of the file or directory to rename. (param $old_path string) - ;; The working directory at which the resolution of the new path starts. + ;;; The working directory at which the resolution of the new path starts. (param $new_fd $fd_t) - ;; The destination path to which to rename the file or directory. + ;;; The destination path to which to rename the file or directory. (param $new_path string) (result $error $errno_t) ) - ;; Create a symbolic link. - ;; Note: This is similar to `symlinkat` in POSIX. + ;;; Create a symbolic link. + ;;; Note: This is similar to `symlinkat` in POSIX. (@interface func (export "path_symlink") - ;; The contents of the symbolic link. + ;;; The contents of the symbolic link. (param $old_path string) (param $fd $fd_t) - ;; The destination path at which to create the symbolic link. + ;;; The destination path at which to create the symbolic link. (param $new_path string) (result $error $errno_t) ) - ;; Unlink a file. - ;; Return `EISDIR` if the path refers to a directory. - ;; Note: This is similar to `unlinkat(fd, path, 0)` in POSIX. + ;;; Unlink a file. + ;;; Return `EISDIR` if the path refers to a directory. + ;;; Note: This is similar to `unlinkat(fd, path, 0)` in POSIX. (@interface func (export "path_unlink_file") (param $fd $fd_t) - ;; The path to a file to unlink. + ;;; The path to a file to unlink. (param $path string) (result $error $errno_t) ) - ;; Concurrently poll for the occurrence of a set of events. + ;;; Concurrently poll for the occurrence of a set of events. (@interface func (export "poll_oneoff") - ;; The events to which to subscribe. + ;;; The events to which to subscribe. (param $in (@witx const_pointer $subscription_t)) - ;; The events that have occurred. + ;;; The events that have occurred. (param $out (@witx pointer $event_t)) - ;; Both the number of subscriptions and events. + ;;; Both the number of subscriptions and events. (param $nsubscriptions $size_t) (result $error $errno_t) - ;; The number of events stored. + ;;; The number of events stored. (result $nevents $size_t) ) - ;; Terminate the process normally. An exit code of 0 indicates successful - ;; termination of the program. The meanings of other values is dependent on - ;; the environment. + ;;; Terminate the process normally. An exit code of 0 indicates successful + ;;; termination of the program. The meanings of other values is dependent on + ;;; the environment. (@interface func (export "proc_exit") - ;; The exit code returned by the process. + ;;; The exit code returned by the process. (param $rval $exitcode_t) ) - ;; Send a signal to the process of the calling thread. - ;; Note: This is similar to `raise` in POSIX. + ;;; Send a signal to the process of the calling thread. + ;;; Note: This is similar to `raise` in POSIX. (@interface func (export "proc_raise") - ;; The signal condition to trigger. + ;;; The signal condition to trigger. (param $sig $signal_t) (result $error $errno_t) ) - ;; Temporarily yield execution of the calling thread. - ;; Note: This is similar to `sched_yield` in POSIX. + ;;; Temporarily yield execution of the calling thread. + ;;; Note: This is similar to `sched_yield` in POSIX. (@interface func (export "sched_yield") (result $error $errno_t) ) - ;; Write high-quality random data into a buffer. - ;; This function blocks when the implementation is unable to immediately - ;; provide sufficient high-quality random data. - ;; This function may execute slowly, so when large mounts of random data are - ;; required, it's advisable to use this function to seed a pseudo-random - ;; number generator, rather than to provide the random data directly. + ;;; Write high-quality random data into a buffer. + ;;; This function blocks when the implementation is unable to immediately + ;;; provide sufficient high-quality random data. + ;;; This function may execute slowly, so when large mounts of random data are + ;;; required, it's advisable to use this function to seed a pseudo-random + ;;; number generator, rather than to provide the random data directly. (@interface func (export "random_get") - ;; The buffer to fill with random data. + ;;; The buffer to fill with random data. (param $buf (@witx pointer u8)) (param $buf_len $size_t) (result $error $errno_t) ) - ;; Receive a message from a socket. - ;; Note: This is similar to `recv` in POSIX, though it also supports reading - ;; the data into multiple buffers in the manner of `readv`. + ;;; Receive a message from a socket. + ;;; Note: This is similar to `recv` in POSIX, though it also supports reading + ;;; the data into multiple buffers in the manner of `readv`. (@interface func (export "sock_recv") (param $fd $fd_t) - ;; List of scatter/gather vectors to which to store data. + ;;; List of scatter/gather vectors to which to store data. (param $ri_data $iovec_t_array) - ;; Message flags. + ;;; Message flags. (param $ri_flags $riflags_t) (result $error $errno_t) - ;; Number of bytes stored in ri_data. + ;;; Number of bytes stored in ri_data. (result $ro_datalen $size_t) - ;; Message flags. + ;;; Message flags. (result $ro_flags $roflags_t) ) - ;; Send a message on a socket. - ;; Note: This is similar to `send` in POSIX, though it also supports writing - ;; the data from multiple buffers in the manner of `writev`. + ;;; Send a message on a socket. + ;;; Note: This is similar to `send` in POSIX, though it also supports writing + ;;; the data from multiple buffers in the manner of `writev`. (@interface func (export "sock_send") (param $fd $fd_t) - ;; List of scatter/gather vectors to which to retrieve data + ;;; List of scatter/gather vectors to which to retrieve data (param $si_data $ciovec_t_array) - ;; Message flags. + ;;; Message flags. (param $si_flags $siflags_t) (result $error $errno_t) - ;; Number of bytes transmitted. + ;;; Number of bytes transmitted. (result $so_datalen $size_t) ) - ;; Shut down socket send and receive channels. - ;; Note: This is similar to `shutdown` in POSIX. + ;;; Shut down socket send and receive channels. + ;;; Note: This is similar to `shutdown` in POSIX. (@interface func (export "sock_shutdown") (param $fd $fd_t) - ;; Which channels on the socket to shut down. + ;;; Which channels on the socket to shut down. (param $how $sdflags_t) (result $error $errno_t) ) diff --git a/phases/snapshot/witx/typenames.witx b/phases/snapshot/witx/typenames.witx index 1a45be1fd..68f6fac4a 100644 --- a/phases/snapshot/witx/typenames.witx +++ b/phases/snapshot/witx/typenames.witx @@ -7,291 +7,291 @@ (typename $size_t u32) -;; Non-negative file size or length of a region within a file. +;;; Non-negative file size or length of a region within a file. (typename $filesize_t u64) -;; Timestamp in nanoseconds. +;;; Timestamp in nanoseconds. (typename $timestamp_t u64) -;; Identifiers for clocks. +;;; Identifiers for clocks. (typename $clockid_t (enum u32 - ;; The clock measuring real time. Time value zero corresponds with - ;; 1970-01-01T00:00:00Z. + ;;; The clock measuring real time. Time value zero corresponds with + ;;; 1970-01-01T00:00:00Z. $CLOCK_REALTIME - ;; The store-wide monotonic clock, which is defined as a clock measuring - ;; real time, whose value cannot be adjusted and which cannot have negative - ;; clock jumps. The epoch of this clock is undefined. The absolute time - ;; value of this clock therefore has no meaning. + ;;; The store-wide monotonic clock, which is defined as a clock measuring + ;;; real time, whose value cannot be adjusted and which cannot have negative + ;;; clock jumps. The epoch of this clock is undefined. The absolute time + ;;; value of this clock therefore has no meaning. $CLOCK_MONOTONIC - ;; The CPU-time clock associated with the current process. + ;;; The CPU-time clock associated with the current process. $CLOCK_PROCESS_CPUTIME_ID - ;; The CPU-time clock associated with the current thread. + ;;; The CPU-time clock associated with the current thread. $CLOCK_THREAD_CPUTIME_ID ) ) -;; Error codes returned by functions. -;; 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. +;;; Error codes returned by functions. +;;; 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. (typename $errno_t (enum u16 - ;; No error occurred. System call completed successfully. + ;;; No error occurred. System call completed successfully. $ESUCCESS - ;; Argument list too long. + ;;; Argument list too long. $E2BIG - ;; Permission denied. + ;;; Permission denied. $EACCES - ;; Address in use. + ;;; Address in use. $EADDRINUSE - ;; Address not available. + ;;; Address not available. $EADDRNOTAVAIL - ;; Address family not supported. + ;;; Address family not supported. $EAFNOSUPPORT - ;; Resource unavailable, or operation would block. + ;;; Resource unavailable, or operation would block. $EAGAIN - ;; Connection already in progress. + ;;; Connection already in progress. $EALREADY - ;; Bad file descriptor. + ;;; Bad file descriptor. $EBADF - ;; Bad message. + ;;; Bad message. $EBADMSG - ;; Device or resource busy. + ;;; Device or resource busy. $EBUSY - ;; Operation canceled. + ;;; Operation canceled. $ECANCELED - ;; No child processes. + ;;; No child processes. $ECHILD - ;; Connection aborted. + ;;; Connection aborted. $ECONNABORTED - ;; Connection refused. + ;;; Connection refused. $ECONNREFUSED - ;; Connection reset. + ;;; Connection reset. $ECONNRESET - ;; Resource deadlock would occur. + ;;; Resource deadlock would occur. $EDEADLK - ;; Destination address required. + ;;; Destination address required. $EDESTADDRREQ - ;; Mathematics argument out of domain of function. + ;;; Mathematics argument out of domain of function. $EDOM - ;; Reserved. + ;;; Reserved. $EDQUOT - ;; File exists. + ;;; File exists. $EEXIST - ;; Bad address. + ;;; Bad address. $EFAULT - ;; File too large. + ;;; File too large. $EFBIG - ;; Host is unreachable. + ;;; Host is unreachable. $EHOSTUNREACH - ;; Identifier removed. + ;;; Identifier removed. $EIDRM - ;; Illegal byte sequence. + ;;; Illegal byte sequence. $EILSEQ - ;; Operation in progress. + ;;; Operation in progress. $EINPROGRESS - ;; Interrupted function. + ;;; Interrupted function. $EINTR - ;; Invalid argument. + ;;; Invalid argument. $EINVAL - ;; I/O error. + ;;; I/O error. $EIO - ;; Socket is connected. + ;;; Socket is connected. $EISCONN - ;; Is a directory. + ;;; Is a directory. $EISDIR - ;; Too many levels of symbolic links. + ;;; Too many levels of symbolic links. $ELOOP - ;; File descriptor value too large. + ;;; File descriptor value too large. $EMFILE - ;; Too many links. + ;;; Too many links. $EMLINK - ;; Message too large. + ;;; Message too large. $EMSGSIZE - ;; Reserved. + ;;; Reserved. $EMULTIHOP - ;; Filename too long. + ;;; Filename too long. $ENAMETOOLONG - ;; Network is down. + ;;; Network is down. $ENETDOWN - ;; Connection aborted by network. + ;;; Connection aborted by network. $ENETRESET - ;; Network unreachable. + ;;; Network unreachable. $ENETUNREACH - ;; Too many files open in system. + ;;; Too many files open in system. $ENFILE - ;; No buffer space available. + ;;; No buffer space available. $ENOBUFS - ;; No such device. + ;;; No such device. $ENODEV - ;; No such file or directory. + ;;; No such file or directory. $ENOENT - ;; Executable file format error. + ;;; Executable file format error. $ENOEXEC - ;; No locks available. + ;;; No locks available. $ENOLCK - ;; Reserved. + ;;; Reserved. $ENOLINK - ;; Not enough space. + ;;; Not enough space. $ENOMEM - ;; No message of the desired type. + ;;; No message of the desired type. $ENOMSG - ;; Protocol not available. + ;;; Protocol not available. $ENOPROTOOPT - ;; No space left on device. + ;;; No space left on device. $ENOSPC - ;; Function not supported. + ;;; Function not supported. $ENOSYS - ;; The socket is not connected. + ;;; The socket is not connected. $ENOTCONN - ;; Not a directory or a symbolic link to a directory. + ;;; Not a directory or a symbolic link to a directory. $ENOTDIR - ;; Directory not empty. + ;;; Directory not empty. $ENOTEMPTY - ;; State not recoverable. + ;;; State not recoverable. $ENOTRECOVERABLE - ;; Not a socket. + ;;; Not a socket. $ENOTSOCK - ;; Not supported, or operation not supported on socket. + ;;; Not supported, or operation not supported on socket. $ENOTSUP - ;; Inappropriate I/O control operation. + ;;; Inappropriate I/O control operation. $ENOTTY - ;; No such device or address. + ;;; No such device or address. $ENXIO - ;; Value too large to be stored in data type. + ;;; Value too large to be stored in data type. $EOVERFLOW - ;; Previous owner died. + ;;; Previous owner died. $EOWNERDEAD - ;; Operation not permitted. + ;;; Operation not permitted. $EPERM - ;; Broken pipe. + ;;; Broken pipe. $EPIPE - ;; Protocol error. + ;;; Protocol error. $EPROTO - ;; Protocol not supported. + ;;; Protocol not supported. $EPROTONOSUPPORT - ;; Protocol wrong type for socket. + ;;; Protocol wrong type for socket. $EPROTOTYPE - ;; Result too large. + ;;; Result too large. $ERANGE - ;; Read-only file system. + ;;; Read-only file system. $EROFS - ;; Invalid seek. + ;;; Invalid seek. $ESPIPE - ;; No such process. + ;;; No such process. $ESRCH - ;; Reserved. + ;;; Reserved. $ESTALE - ;; Connection timed out. + ;;; Connection timed out. $ETIMEDOUT - ;; Text file busy. + ;;; Text file busy. $ETXTBSY - ;; Cross-device link. + ;;; Cross-device link. $EXDEV - ;; Extension: Capabilities insufficient. + ;;; Extension: Capabilities insufficient. $ENOTCAPABLE ) ) -;; File descriptor rights, determining which actions may be performed. +;;; File descriptor rights, determining which actions may be performed. (typename $rights_t (flags u64 - ;; The right to invoke `fd_datasync`. + ;;; The right to invoke `fd_datasync`. ;; - ;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke - ;; `path_open` with `FDFLAG_DSYNC`. + ;;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke + ;;; `path_open` with `FDFLAG_DSYNC`. $RIGHT_FD_DATASYNC - ;; The right to invoke `fd_read` and `sock_recv`. + ;;; The right to invoke `fd_read` and `sock_recv`. ;; - ;; If `RIGHT_FD_SEEK` is set, includes the right to invoke `fd_pread`. + ;;; If `RIGHT_FD_SEEK` is set, includes the right to invoke `fd_pread`. $RIGHT_FD_READ - ;; The right to invoke `fd_seek`. This flag implies `RIGHT_FD_TELL`. + ;;; The right to invoke `fd_seek`. This flag implies `RIGHT_FD_TELL`. $RIGHT_FD_SEEK - ;; The right to invoke `fd_fdstat_set_flags`. + ;;; The right to invoke `fd_fdstat_set_flags`. $RIGHT_FD_FDSTAT_SET_FLAGS - ;; The right to invoke `fd_sync`. + ;;; The right to invoke `fd_sync`. ;; - ;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke - ;; `path_open` with `FDFLAG_RSYNC` and `FDFLAG_DSYNC`. + ;;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke + ;;; `path_open` with `FDFLAG_RSYNC` and `FDFLAG_DSYNC`. $RIGHT_FD_SYNC - ;; The right to invoke `fd_seek` in such a way that the file offset - ;; remains unaltered (i.e., `WHENCE_CUR` with offset zero), or to - ;; invoke `fd_tell`. + ;;; The right to invoke `fd_seek` in such a way that the file offset + ;;; remains unaltered (i.e., `WHENCE_CUR` with offset zero), or to + ;;; invoke `fd_tell`. $RIGHT_FD_TELL - ;; The right to invoke `fd_write` and `sock_send`. - ;; If `RIGHT_FD_SEEK` is set, includes the right to invoke `fd_pwrite`. + ;;; The right to invoke `fd_write` and `sock_send`. + ;;; If `RIGHT_FD_SEEK` is set, includes the right to invoke `fd_pwrite`. $RIGHT_FD_WRITE - ;; The right to invoke `fd_advise`. + ;;; The right to invoke `fd_advise`. $RIGHT_FD_ADVISE - ;; The right to invoke `fd_allocate`. + ;;; The right to invoke `fd_allocate`. $RIGHT_FD_ALLOCATE - ;; The right to invoke `path_create_directory`. + ;;; The right to invoke `path_create_directory`. $RIGHT_PATH_CREATE_DIRECTORY - ;; If `RIGHT_PATH_OPEN` is set, the right to invoke `path_open` with `O_CREAT`. + ;;; If `RIGHT_PATH_OPEN` is set, the right to invoke `path_open` with `O_CREAT`. $RIGHT_PATH_CREATE_FILE - ;; The right to invoke `path_link` with the file descriptor as the - ;; source directory. + ;;; The right to invoke `path_link` with the file descriptor as the + ;;; source directory. $RIGHT_PATH_LINK_SOURCE - ;; The right to invoke `path_link` with the file descriptor as the - ;; target directory. + ;;; The right to invoke `path_link` with the file descriptor as the + ;;; target directory. $RIGHT_PATH_LINK_TARGET - ;; The right to invoke `path_open`. + ;;; The right to invoke `path_open`. $RIGHT_PATH_OPEN - ;; The right to invoke `fd_readdir`. + ;;; The right to invoke `fd_readdir`. $RIGHT_FD_READDIR - ;; The right to invoke `path_readlink`. + ;;; The right to invoke `path_readlink`. $RIGHT_PATH_READLINK - ;; The right to invoke `path_rename` with the file descriptor as the source directory. + ;;; The right to invoke `path_rename` with the file descriptor as the source directory. $RIGHT_PATH_RENAME_SOURCE - ;; The right to invoke `path_rename` with the file descriptor as the target directory. + ;;; The right to invoke `path_rename` with the file descriptor as the target directory. $RIGHT_PATH_RENAME_TARGET - ;; The right to invoke `path_filestat_get`. + ;;; The right to invoke `path_filestat_get`. $RIGHT_PATH_FILESTAT_GET - ;; The right to change a file's size (there is no `path_filestat_set_size`). - ;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke `path_open` with `O_TRUNC`. + ;;; The right to change a file's size (there is no `path_filestat_set_size`). + ;;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke `path_open` with `O_TRUNC`. $RIGHT_PATH_FILESTAT_SET_SIZE - ;; The right to invoke `path_filestat_set_times`. + ;;; The right to invoke `path_filestat_set_times`. $RIGHT_PATH_FILESTAT_SET_TIMES - ;; The right to invoke `fd_filestat_get`. + ;;; The right to invoke `fd_filestat_get`. $RIGHT_FD_FILESTAT_GET - ;; The right to invoke `fd_filestat_set_size`. + ;;; The right to invoke `fd_filestat_set_size`. $RIGHT_FD_FILESTAT_SET_SIZE - ;; The right to invoke `fd_filestat_set_times`. + ;;; The right to invoke `fd_filestat_set_times`. $RIGHT_FD_FILESTAT_SET_TIMES - ;; The right to invoke `path_symlink`. + ;;; The right to invoke `path_symlink`. $RIGHT_PATH_SYMLINK - ;; The right to invoke `path_remove_directory`. + ;;; The right to invoke `path_remove_directory`. $RIGHT_PATH_REMOVE_DIRECTORY - ;; The right to invoke `path_unlink_file`. + ;;; The right to invoke `path_unlink_file`. $RIGHT_PATH_UNLINK_FILE - ;; If `RIGHT_FD_READ` is set, includes the right to invoke `poll_oneoff` to subscribe to `EVENTTYPE_FD_READ`. - ;; If `RIGHT_FD_WRITE` is set, includes the right to invoke `poll_oneoff` to subscribe to `EVENTTYPE_FD_WRITE`. + ;;; If `RIGHT_FD_READ` is set, includes the right to invoke `poll_oneoff` to subscribe to `EVENTTYPE_FD_READ`. + ;;; If `RIGHT_FD_WRITE` is set, includes the right to invoke `poll_oneoff` to subscribe to `EVENTTYPE_FD_WRITE`. $RIGHT_POLL_FD_READWRITE - ;; The right to invoke `sock_shutdown`. + ;;; The right to invoke `sock_shutdown`. $RIGHT_SOCK_SHUTDOWN ) ) -;; A file descriptor index. +;;; A file descriptor index. (typename $fd_t u32) -;; A region of memory for scatter/gather reads. +;;; A region of memory for scatter/gather reads. (typename $iovec_t (struct - ;; The address of the buffer to be filled. + ;;; The address of the buffer to be filled. (field $buf (@witx pointer u8)) - ;; The length of the buffer to be filled. + ;;; The length of the buffer to be filled. (field $buf_len $size_t) ) ) -;; A region of memory for scatter/gather writes. +;;; A region of memory for scatter/gather writes. (typename $ciovec_t (struct - ;; The address of the buffer to be written. + ;;; The address of the buffer to be written. (field $buf (@witx const_pointer u8)) - ;; The length of the buffer to be written. + ;;; The length of the buffer to be written. (field $buf_len $size_t) ) ) @@ -299,469 +299,469 @@ (typename $iovec_t_array (array $iovec_t)) (typename $ciovec_t_array (array $ciovec_t)) -;; Relative offset within a file. +;;; Relative offset within a file. (typename $filedelta_t s64) -;; The position relative to which to set the offset of the file descriptor. +;;; The position relative to which to set the offset of the file descriptor. (typename $whence_t (enum u8 - ;; Seek relative to start-of-file. + ;;; Seek relative to start-of-file. $WHENCE_SET - ;; Seek relative to current position. + ;;; Seek relative to current position. $WHENCE_CUR - ;; Seek relative to end-of-file. + ;;; Seek relative to end-of-file. $WHENCE_END ) ) -;; A reference to the offset of a directory entry. -;; -;; The value 0 signifies the start of the directory. +;;; A reference to the offset of a directory entry. +;;; +;;; The value 0 signifies the start of the directory. (typename $dircookie_t u64) -;; The type for the $d_namlen field of $dirent_t. +;;; The type for the $d_namlen field of $dirent_t. (typename $dirnamlen_t u32) -;; File serial number that is unique within its file system. +;;; File serial number that is unique within its file system. (typename $inode_t u64) -;; The type of a file descriptor or file. +;;; The type of a file descriptor or file. (typename $filetype_t (enum u8 - ;; The type of the file descriptor or file is unknown or is different from any of the other types specified. + ;;; The type of the file descriptor or file is unknown or is different from any of the other types specified. $FILETYPE_UNKNOWN - ;; The file descriptor or file refers to a block device inode. + ;;; The file descriptor or file refers to a block device inode. $FILETYPE_BLOCK_DEVICE - ;; The file descriptor or file refers to a character device inode. + ;;; The file descriptor or file refers to a character device inode. $FILETYPE_CHARACTER_DEVICE - ;; The file descriptor or file refers to a directory inode. + ;;; The file descriptor or file refers to a directory inode. $FILETYPE_DIRECTORY - ;; The file descriptor or file refers to a regular file inode. + ;;; The file descriptor or file refers to a regular file inode. $FILETYPE_REGULAR_FILE - ;; The file descriptor or file refers to a datagram socket. + ;;; The file descriptor or file refers to a datagram socket. $FILETYPE_SOCKET_DGRAM - ;; The file descriptor or file refers to a byte-stream socket. + ;;; The file descriptor or file refers to a byte-stream socket. $FILETYPE_SOCKET_STREAM - ;; The file refers to a symbolic link inode. + ;;; The file refers to a symbolic link inode. $FILETYPE_SYMBOLIC_LINK ) ) -;; A directory entry. +;;; A directory entry. (typename $dirent_t (struct - ;; The offset of the next directory entry stored in this directory. + ;;; The offset of the next directory entry stored in this directory. (field $d_next $dircookie_t) - ;; The serial number of the file referred to by this directory entry. + ;;; The serial number of the file referred to by this directory entry. (field $d_ino $inode_t) - ;; The length of the name of the directory entry. + ;;; The length of the name of the directory entry. (field $d_namlen $dirnamlen_t) - ;; The type of the file referred to by this directory entry. + ;;; The type of the file referred to by this directory entry. (field $d_type $filetype_t) ) ) -;; File or memory access pattern advisory information. +;;; File or memory access pattern advisory information. (typename $advice_t (enum u8 - ;; The application has no advice to give on its behavior with respect to the specified data. + ;;; The application has no advice to give on its behavior with respect to the specified data. $ADVICE_NORMAL - ;; The application expects to access the specified data sequentially from lower offsets to higher offsets. + ;;; The application expects to access the specified data sequentially from lower offsets to higher offsets. $ADVICE_SEQUENTIAL - ;; The application expects to access the specified data in a random order. + ;;; The application expects to access the specified data in a random order. $ADVICE_RANDOM - ;; The application expects to access the specified data in the near future. + ;;; The application expects to access the specified data in the near future. $ADVICE_WILLNEED - ;; The application expects that it will not access the specified data in the near future. + ;;; The application expects that it will not access the specified data in the near future. $ADVICE_DONTNEED - ;; The application expects to access the specified data once and then not reuse it thereafter. + ;;; The application expects to access the specified data once and then not reuse it thereafter. $ADVICE_NOREUSE ) ) -;; File descriptor flags. +;;; File descriptor flags. (typename $fdflags_t (flags u16 - ;; Append mode: Data written to the file is always appended to the file's end. + ;;; Append mode: Data written to the file is always appended to the file's end. $FDFLAG_APPEND - ;; Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized. + ;;; Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized. $FDFLAG_DSYNC - ;; Non-blocking mode. + ;;; Non-blocking mode. $FDFLAG_NONBLOCK - ;; Synchronized read I/O operations. + ;;; Synchronized read I/O operations. $FDFLAG_RSYNC - ;; Write according to synchronized I/O file integrity completion. In - ;; addition to synchronizing the data stored in the file, the implementation - ;; may also synchronously update the file's metadata. + ;;; Write according to synchronized I/O file integrity completion. In + ;;; addition to synchronizing the data stored in the file, the implementation + ;;; may also synchronously update the file's metadata. $FDFLAG_SYNC ) ) -;; File descriptor attributes. +;;; File descriptor attributes. (typename $fdstat_t (struct - ;; File type. + ;;; File type. (field $fs_filetype $filetype_t) - ;; File descriptor flags. + ;;; File descriptor flags. (field $fs_flags $fdflags_t) - ;; Rights that apply to this file descriptor. + ;;; Rights that apply to this file descriptor. (field $fs_rights_base $rights_t) - ;; Maximum set of rights that may be installed on new file descriptors that - ;; are created through this file descriptor, e.g., through `path_open`. + ;;; Maximum set of rights that may be installed on new file descriptors that + ;;; are created through this file descriptor, e.g., through `path_open`. (field $fs_rights_inheriting $rights_t) ) ) -;; Identifier for a device containing a file system. Can be used in combination -;; with `inode_t` to uniquely identify a file or directory in the filesystem. +;;; Identifier for a device containing a file system. Can be used in combination +;;; with `inode_t` to uniquely identify a file or directory in the filesystem. (typename $device_t u64) -;; Which file time attributes to adjust. +;;; Which file time attributes to adjust. (typename $fstflags_t (flags u16 - ;; Adjust the last data access timestamp to the value stored in `filestat_t::st_atim`. + ;;; Adjust the last data access timestamp to the value stored in `filestat_t::st_atim`. $FILESTAT_SET_ATIM - ;; Adjust the last data access timestamp to the time of clock `CLOCK_REALTIME`. + ;;; Adjust the last data access timestamp to the time of clock `CLOCK_REALTIME`. $FILESTAT_SET_ATIM_NOW - ;; Adjust the last data modification timestamp to the value stored in `filestat_t::st_mtim`. + ;;; Adjust the last data modification timestamp to the value stored in `filestat_t::st_mtim`. $FILESTAT_SET_MTIM - ;; Adjust the last data modification timestamp to the time of clock `CLOCK_REALTIME`. + ;;; Adjust the last data modification timestamp to the time of clock `CLOCK_REALTIME`. $FILESTAT_SET_MTIM_NOW ) ) -;; Flags determining the method of how paths are resolved. +;;; Flags determining the method of how paths are resolved. (typename $lookupflags_t (flags u32 - ;; As long as the resolved path corresponds to a symbolic link, it is expanded. + ;;; As long as the resolved path corresponds to a symbolic link, it is expanded. $LOOKUP_SYMLINK_FOLLOW ) ) -;; Open flags used by `path_open`. +;;; Open flags used by `path_open`. (typename $oflags_t (flags u16 - ;; Create file if it does not exist. + ;;; Create file if it does not exist. $O_CREAT - ;; Fail if not a directory. + ;;; Fail if not a directory. $O_DIRECTORY - ;; Fail if file already exists. + ;;; Fail if file already exists. $O_EXCL - ;; Truncate file to size 0. + ;;; Truncate file to size 0. $O_TRUNC ) ) -;; Number of hard links to an inode. +;;; Number of hard links to an inode. (typename $linkcount_t u64) -;; File attributes. +;;; File attributes. (typename $filestat_t (struct - ;; Device ID of device containing the file. + ;;; Device ID of device containing the file. (field $st_dev $device_t) - ;; File serial number. + ;;; File serial number. (field $st_ino $inode_t) - ;; File type. + ;;; File type. (field $st_filetype $filetype_t) - ;; Number of hard links to the file. + ;;; Number of hard links to the file. (field $st_nlink $linkcount_t) - ;; For regular files, the file size in bytes. For symbolic links, the length in bytes of the pathname contained in the symbolic link. + ;;; For regular files, the file size in bytes. For symbolic links, the length in bytes of the pathname contained in the symbolic link. (field $st_size $filesize_t) - ;; Last data access timestamp. + ;;; Last data access timestamp. (field $st_atim $timestamp_t) - ;; Last data modification timestamp. + ;;; Last data modification timestamp. (field $st_mtim $timestamp_t) - ;; Last file status change timestamp. + ;;; Last file status change timestamp. (field $st_ctim $timestamp_t) ) ) -;; User-provided value that may be attached to objects that is retained when -;; extracted from the implementation. +;;; User-provided value that may be attached to objects that is retained when +;;; extracted from the implementation. (typename $userdata_t u64) -;; Type of a subscription to an event or its occurrence. +;;; Type of a subscription to an event or its occurrence. (typename $eventtype_t (enum u8 - ;; The time value of clock `subscription_t::u.clock.clock_id` has - ;; reached timestamp `subscription_t::u.clock.timeout`. + ;;; The time value of clock `subscription_t::u.clock.clock_id` has + ;;; reached timestamp `subscription_t::u.clock.timeout`. $EVENTTYPE_CLOCK - ;; File descriptor `subscription_t::u.fd_readwrite.fd` has data - ;; available for reading. This event always triggers for regular files. + ;;; File descriptor `subscription_t::u.fd_readwrite.fd` has data + ;;; available for reading. This event always triggers for regular files. $EVENTTYPE_FD_READ - ;; File descriptor `subscription_t::u.fd_readwrite.fd` has capacity - ;; available for writing. This event always triggers for regular files. + ;;; File descriptor `subscription_t::u.fd_readwrite.fd` has capacity + ;;; available for writing. This event always triggers for regular files. $EVENTTYPE_FD_WRITE ) ) -;; The state of the file descriptor subscribed to with -;; `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`. +;;; The state of the file descriptor subscribed to with +;;; `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`. (typename $eventrwflags_t (flags u16 - ;; The peer of this socket has closed or disconnected. + ;;; The peer of this socket has closed or disconnected. $EVENT_FD_READWRITE_HANGUP ) ) -;; The contents of an $event_t when type is `EVENTTYPE_FD_READ` or -;; `EVENTTYPE_FD_WRITE`. +;;; The contents of an $event_t when type is `EVENTTYPE_FD_READ` or +;;; `EVENTTYPE_FD_WRITE`. (typename $event_fd_readwrite_t (struct - ;; The number of bytes available for reading or writing. + ;;; The number of bytes available for reading or writing. (field $nbytes $filesize_t) - ;; The state of the file descriptor. + ;;; The state of the file descriptor. (field $flags $eventrwflags_t) ) ) -;; The contents of an $event_t. +;;; The contents of an $event_t. (typename $event_u (union - ;; When type is `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`: + ;;; When type is `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`: (field $fd_readwrite $event_fd_readwrite_t) ) ) -;; An event that occurred. +;;; An event that occurred. (typename $event_t (struct - ;; User-provided value that got attached to `subscription_t::userdata`. + ;;; User-provided value that got attached to `subscription_t::userdata`. (field $userdata $userdata_t) - ;; If non-zero, an error that occurred while processing the subscription request. + ;;; If non-zero, an error that occurred while processing the subscription request. (field $error $errno_t) - ;; The type of the event that occurred. + ;;; The type of the event that occurred. (field $type $eventtype_t) - ;; The contents of the event. + ;;; The contents of the event. (field $u $event_u) ) ) -;; Flags determining how to interpret the timestamp provided in -;; `subscription_t::u.clock.timeout.` +;;; Flags determining how to interpret the timestamp provided in +;;; `subscription_t::u.clock.timeout.` (typename $subclockflags_t (flags u16 - ;; If set, treat the timestamp provided in - ;; `subscription_t::u.clock.timeout` as an absolute timestamp of clock - ;; `subscription_t::u.clock.clock_id.` If clear, treat the timestamp - ;; provided in `subscription_t::u.clock.timeout` relative to the - ;; current time value of clock `subscription_t::u.clock.clock_id.` + ;;; If set, treat the timestamp provided in + ;;; `subscription_t::u.clock.timeout` as an absolute timestamp of clock + ;;; `subscription_t::u.clock.clock_id.` If clear, treat the timestamp + ;;; provided in `subscription_t::u.clock.timeout` relative to the + ;;; current time value of clock `subscription_t::u.clock.clock_id.` $SUBSCRIPTION_CLOCK_ABSTIME ) ) -;; The contents of a $subscription_t when type is `EVENTTYPE_CLOCK`. +;;; The contents of a $subscription_t when type is `EVENTTYPE_CLOCK`. (typename $subscription_clock_t (struct - ;; The clock against which to compare the timestamp. + ;;; The clock against which to compare the timestamp. (field $clock_id $clockid_t) - ;; The absolute or relative timestamp. + ;;; The absolute or relative timestamp. (field $timeout $timestamp_t) - ;; The amount of time that the implementation may wait additionally - ;; to coalesce with other events. + ;;; The amount of time that the implementation may wait additionally + ;;; to coalesce with other events. (field $precision $timestamp_t) - ;; Flags specifying whether the timeout is absolute or relative + ;;; Flags specifying whether the timeout is absolute or relative (field $flags $subclockflags_t) ) ) -;; The contents of a $subscription_t when type is type is -;; `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`. +;;; The contents of a $subscription_t when type is type is +;;; `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`. (typename $subscription_fd_readwrite_t (struct - ;; The file descriptor on which to wait for it to become ready for reading or writing. + ;;; The file descriptor on which to wait for it to become ready for reading or writing. (field $file_descriptor $fd_t) ) ) -;; The contents of a $subscription_t. +;;; The contents of a $subscription_t. (typename $subscription_u (union - ;; When type is `EVENTTYPE_CLOCK`: + ;;; When type is `EVENTTYPE_CLOCK`: (field $clock $subscription_clock_t) - ;; When type is `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`: + ;;; When type is `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`: (field $fd_readwrite $subscription_fd_readwrite_t) ) ) -;; Subscription to an event. +;;; Subscription to an event. (typename $subscription_t (struct - ;; User-provided value that is attached to the subscription in the - ;; implementation and returned through `event_t::userdata`. + ;;; User-provided value that is attached to the subscription in the + ;;; implementation and returned through `event_t::userdata`. (field $userdata $userdata_t) - ;; The type of the event to which to subscribe. + ;;; The type of the event to which to subscribe. (field $type $eventtype_t) - ;; The contents of the subscription. + ;;; The contents of the subscription. (field $u $subscription_u) ) ) -;; Exit code generated by a process when exiting. +;;; Exit code generated by a process when exiting. (typename $exitcode_t u32) -;; Signal condition. +;;; Signal condition. (typename $signal_t (enum u8 - ;; No signal. Note that POSIX has special semantics for `kill(pid, 0)`, - ;; so this value is reserved. + ;;; No signal. Note that POSIX has special semantics for `kill(pid, 0)`, + ;;; so this value is reserved. $SIGNONE - ;; Hangup. - ;; Action: Terminates the process. + ;;; Hangup. + ;;; Action: Terminates the process. $SIGHUP - ;; Terminate interrupt signal. - ;; Action: Terminates the process. + ;;; Terminate interrupt signal. + ;;; Action: Terminates the process. $SIGINT - ;; Terminal quit signal. - ;; Action: Terminates the process. + ;;; Terminal quit signal. + ;;; Action: Terminates the process. $SIGQUIT - ;; Illegal instruction. - ;; Action: Terminates the process. + ;;; Illegal instruction. + ;;; Action: Terminates the process. $SIGILL - ;; Trace/breakpoint trap. - ;; Action: Terminates the process. + ;;; Trace/breakpoint trap. + ;;; Action: Terminates the process. $SIGTRAP - ;; Process abort signal. - ;; Action: Terminates the process. + ;;; Process abort signal. + ;;; Action: Terminates the process. $SIGABRT - ;; Access to an undefined portion of a memory object. - ;; Action: Terminates the process. + ;;; Access to an undefined portion of a memory object. + ;;; Action: Terminates the process. $SIGBUS - ;; Erroneous arithmetic operation. - ;; Action: Terminates the process. + ;;; Erroneous arithmetic operation. + ;;; Action: Terminates the process. $SIGFPE - ;; Kill. - ;; Action: Terminates the process. + ;;; Kill. + ;;; Action: Terminates the process. $SIGKILL - ;; User-defined signal 1. - ;; Action: Terminates the process. + ;;; User-defined signal 1. + ;;; Action: Terminates the process. $SIGUSR1 - ;; Invalid memory reference. - ;; Action: Terminates the process. + ;;; Invalid memory reference. + ;;; Action: Terminates the process. $SIGSEGV - ;; User-defined signal 2. - ;; Action: Terminates the process. + ;;; User-defined signal 2. + ;;; Action: Terminates the process. $SIGUSR2 - ;; Write on a pipe with no one to read it. - ;; Action: Ignored. + ;;; Write on a pipe with no one to read it. + ;;; Action: Ignored. $SIGPIPE - ;; Alarm clock. - ;; Action: Terminates the process. + ;;; Alarm clock. + ;;; Action: Terminates the process. $SIGALRM - ;; Termination signal. - ;; Action: Terminates the process. + ;;; Termination signal. + ;;; Action: Terminates the process. $SIGTERM - ;; Child process terminated, stopped, or continued. - ;; Action: Ignored. + ;;; Child process terminated, stopped, or continued. + ;;; Action: Ignored. $SIGCHLD - ;; Continue executing, if stopped. - ;; Action: Continues executing, if stopped. + ;;; Continue executing, if stopped. + ;;; Action: Continues executing, if stopped. $SIGCONT - ;; Stop executing. - ;; Action: Stops executing. + ;;; Stop executing. + ;;; Action: Stops executing. $SIGSTOP - ;; Terminal stop signal. - ;; Action: Stops executing. + ;;; Terminal stop signal. + ;;; Action: Stops executing. $SIGTSTP - ;; Background process attempting read. - ;; Action: Stops executing. + ;;; Background process attempting read. + ;;; Action: Stops executing. $SIGTTIN - ;; Background process attempting write. - ;; Action: Stops executing. + ;;; Background process attempting write. + ;;; Action: Stops executing. $SIGTTOU - ;; High bandwidth data is available at a socket. - ;; Action: Ignored. + ;;; High bandwidth data is available at a socket. + ;;; Action: Ignored. $SIGURG - ;; CPU time limit exceeded. - ;; Action: Terminates the process. + ;;; CPU time limit exceeded. + ;;; Action: Terminates the process. $SIGXCPU - ;; File size limit exceeded. - ;; Action: Terminates the process. + ;;; File size limit exceeded. + ;;; Action: Terminates the process. $SIGXFSZ - ;; Virtual timer expired. - ;; Action: Terminates the process. + ;;; Virtual timer expired. + ;;; Action: Terminates the process. $SIGVTALRM - ;; Profiling timer expired. - ;; Action: Terminates the process. + ;;; Profiling timer expired. + ;;; Action: Terminates the process. $SIGPROF - ;; Window changed. - ;; Action: Ignored. + ;;; Window changed. + ;;; Action: Ignored. $SIGWINCH - ;; I/O possible. - ;; Action: Terminates the process. + ;;; I/O possible. + ;;; Action: Terminates the process. $SIGPOLL - ;; Power failure. - ;; Action: Terminates the process. + ;;; Power failure. + ;;; Action: Terminates the process. $SIGPWR - ;; Bad system call. - ;; Action: Terminates the process. + ;;; Bad system call. + ;;; Action: Terminates the process. $SIGSYS ) ) -;; Flags provided to `sock_recv`. +;;; Flags provided to `sock_recv`. (typename $riflags_t (flags u16 - ;; Returns the message without removing it from the socket's receive queue. + ;;; Returns the message without removing it from the socket's receive queue. $SOCK_RECV_PEEK - ;; On byte-stream sockets, block until the full amount of data can be returned. + ;;; On byte-stream sockets, block until the full amount of data can be returned. $SOCK_RECV_WAITALL ) ) -;; Flags returned by `sock_recv`. +;;; Flags returned by `sock_recv`. (typename $roflags_t (flags u16 - ;; Returned by `sock_recv`: Message data has been truncated. + ;;; Returned by `sock_recv`: Message data has been truncated. $SOCK_RECV_DATA_TRUNCATED ) ) -;; Flags provided to `sock_send`. As there are currently no flags -;; defined, it must be set to zero. +;;; Flags provided to `sock_send`. As there are currently no flags +;;; defined, it must be set to zero. (typename $siflags_t u16) -;; Which channels on a socket to shut down. +;;; Which channels on a socket to shut down. (typename $sdflags_t (flags u8 - ;; Disables further receive operations. + ;;; Disables further receive operations. $SHUT_RD - ;; Disables further send operations. + ;;; Disables further send operations. $SHUT_WR ) ) -;; Identifiers for preopened capabilities. +;;; Identifiers for preopened capabilities. (typename $preopentype_t (enum u8 - ;; A pre-opened directory. + ;;; A pre-opened directory. $PREOPENTYPE_DIR ) ) -;; The contents of a $prestat_t when type is `PREOPENTYPE_DIR`. +;;; The contents of a $prestat_t when type is `PREOPENTYPE_DIR`. (typename $prestat_dir (struct - ;; The length of the directory name for use with `fd_prestat_dir_name`. + ;;; The length of the directory name for use with `fd_prestat_dir_name`. (field $pr_name_len $size_t) ) ) -;; The contents of an $prestat_t. +;;; The contents of an $prestat_t. (typename $prestat_u (union - ;; When type is `PREOPENTYPE_DIR`: + ;;; When type is `PREOPENTYPE_DIR`: (field $dir $prestat_dir) ) ) -;; Information about a pre-opened capability. +;;; Information about a pre-opened capability. (typename $prestat_t (struct - ;; The type of the pre-opened capability. + ;;; The type of the pre-opened capability. (field $pr_type $preopentype_t) - ;; The contents of the information. + ;;; The contents of the information. (field $u $prestat_u) ) ) diff --git a/phases/snapshot/witx/wasi_snapshot_preview1.witx b/phases/snapshot/witx/wasi_snapshot_preview1.witx index 630537416..e69b788dc 100644 --- a/phases/snapshot/witx/wasi_snapshot_preview1.witx +++ b/phases/snapshot/witx/wasi_snapshot_preview1.witx @@ -9,519 +9,522 @@ (use "typenames.witx") (module $wasi_snapshot_preview1 - ;; Linear memory to be accessed by WASI functions that need it. + ;;; Linear memory to be accessed by WASI functions that need it. (import "memory" (memory)) - ;; Read command-line argument data. - ;; The size of the array should match that returned by `wasi_args_sizes_get()` + ;;; Read command-line argument data. + ;;; The size of the array should match that returned by `wasi_args_sizes_get()` (@interface func (export "args_get") (param $argv (@witx pointer (@witx pointer u8))) (param $argv_buf (@witx pointer u8)) (result $error $errno_t) ) - ;; Return command-line argument data sizes. + ;;; Return command-line argument data sizes. (@interface func (export "args_sizes_get") (result $error $errno_t) - ;; The number of arguments. + ;;; The number of arguments. (result $argc $size_t) - ;; The size of the argument string data. + ;;; The size of the argument string data. (result $argv_buf_size $size_t) ) - ;; Read environment variable data. - ;; The sizes of the buffers should match that returned by `environ.sizes_get()`. + ;;; Read environment variable data. + ;;; The sizes of the buffers should match that returned by `environ.sizes_get()`. (@interface func (export "environ_get") (param $environ (@witx pointer (@witx pointer u8))) (param $environ_buf (@witx pointer u8)) (result $error $errno_t) ) - ;; Return command-line argument data sizes. + ;;; Return command-line argument data sizes. (@interface func (export "environ_sizes_get") (result $error $errno_t) - ;; The number of arguments. + ;;; The number of arguments. (result $argc $size_t) - ;; The size of the argument string data. + ;;; The size of the argument string data. (result $argv_buf_size $size_t) ) - ;; Return the resolution of a clock. - ;; Implementations are required to provide a non-zero value for supported clocks. For unsupported clocks, return `WASI_EINVAL` - ;; Note: This is similar to `clock_getres` in POSIX. + ;;; Return the resolution of a clock. + ;;; Implementations are required to provide a non-zero value for supported clocks. For unsupported clocks, return `WASI_EINVAL` + ;;; Note: This is similar to `clock_getres` in POSIX. (@interface func (export "clock_res_get") (result $error $errno_t) - ;; The clock for which to return the resolution. + ;;; The clock for which to return the resolution. (param $clock_id $clockid_t) - ;; The resolution of the clock. + ;;; The resolution of the clock. (result $resolution $timestamp_t) ) - ;; Return the time value of a clock. - ;; Note: This is similar to `clock_gettime` in POSIX. + ;;; Return the time value of a clock. + ;;; Note: This is similar to `clock_gettime` in POSIX. (@interface func (export "clock_time_get") - ;; The clock for which to return the time. + ;;; The clock for which to return the time. (param $clock_id $clockid_t) - ;; The maximum lag (exclusive) that the returned time value may have, compared to its actual value. + ;;; The maximum lag (exclusive) that the returned time value may have, compared to its actual value. (param $precision $timestamp_t) (result $error $errno_t) - ;; The time value of the clock. + ;;; The time value of the clock. (result $time $timestamp_t) ) - ;; Provide file advisory information on a file descriptor. - ;; Note: This is similar to `posix_fadvise` in POSIX. + ;;; Provide file advisory information on a file descriptor. + ;;; Note: This is similar to `posix_fadvise` in POSIX. (@interface func (export "fd_advise") (param $fd $fd_t) - (param $offset $filesize_t) ;; The offset within the file to which the advisory applies. - (param $len $filesize_t) ;; The length of the region to which the advisory applies. - (param $advice $advice_t) ;; The advice. + ;;; The offset within the file to which the advisory applies. + (param $offset $filesize_t) + ;;; The length of the region to which the advisory applies. + (param $len $filesize_t) + ;;; The advice. + (param $advice $advice_t) (result $error $errno_t) ) - ;; Force the allocation of space in a file. - ;; Note: This is similar to `posix_fallocate` in POSIX. + ;;; Force the allocation of space in a file. + ;;; Note: This is similar to `posix_fallocate` in POSIX. (@interface func (export "fd_allocate") (param $fd $fd_t) - ;; The offset at which to start the allocation. + ;;; The offset at which to start the allocation. (param $offset $filesize_t) - ;; The length of the area that is allocated. + ;;; The length of the area that is allocated. (param $len $filesize_t) (result $error $errno_t) ) - ;; Close a file descriptor. - ;; Note: This is similar to `close` in POSIX. + ;;; Close a file descriptor. + ;;; Note: This is similar to `close` in POSIX. (@interface func (export "fd_close") (param $fd $fd_t) (result $error $errno_t) ) - ;; Synchronize the data of a file to disk. - ;; Note: This is similar to `fdatasync` in POSIX. + ;;; Synchronize the data of a file to disk. + ;;; Note: This is similar to `fdatasync` in POSIX. (@interface func (export "fd_datasync") (param $fd $fd_t) (result $error $errno_t) ) - ;; Get the attributes of a file descriptor. - ;; Note: This returns similar flags to `fsync(fd, F_GETFL)` in POSIX, as well as additional fields. + ;;; Get the attributes of a file descriptor. + ;;; Note: This returns similar flags to `fsync(fd, F_GETFL)` in POSIX, as well as additional fields. (@interface func (export "fd_fdstat_get") (param $fd $fd_t) (result $error $errno_t) - ;; The buffer where the file descriptor's attributes are stored. + ;;; The buffer where the file descriptor's attributes are stored. (result $stat $fdstat_t) ) - ;; Adjust the flags associated with a file descriptor. - ;; Note: This is similar to `fcntl(fd, F_SETFL, flags)` in POSIX. + ;;; Adjust the flags associated with a file descriptor. + ;;; Note: This is similar to `fcntl(fd, F_SETFL, flags)` in POSIX. (@interface func (export "fd_fdstat_set_flags") (param $fd $fd_t) - ;; The desired values of the file descriptor flags. + ;;; The desired values of the file descriptor flags. (param $flags $fdflags_t) (result $error $errno_t) ) - ;; Adjust the rights associated with a file descriptor. - ;; This can only be used to remove rights, and returns `ENOTCAPABLE` if called in a way that would attempt to add rights + ;;; Adjust the rights associated with a file descriptor. + ;;; This can only be used to remove rights, and returns `ENOTCAPABLE` if called in a way that would attempt to add rights (@interface func (export "fd_fdstat_set_rights") (param $fd $fd_t) - ;; The desired rights of the file descriptor. + ;;; The desired rights of the file descriptor. (param $fs_rights_base $rights_t) (param $fs_rights_inheriting $rights_t) (result $error $errno_t) ) - ;; Return the attributes of an open file. + ;;; Return the attributes of an open file. (@interface func (export "fd_filestat_get") (param $fd $fd_t) (result $error $errno_t) - ;; The buffer where the file's attributes are stored. + ;;; The buffer where the file's attributes are stored. (result $buf $filestat_t) ) - ;; Adjust the size of an open file. If this increases the file's size, the extra bytes are filled with zeros. - ;; Note: This is similar to `ftruncate` in POSIX. + ;;; Adjust the size of an open file. If this increases the file's size, the extra bytes are filled with zeros. + ;;; Note: This is similar to `ftruncate` in POSIX. (@interface func (export "fd_filestat_set_size") (param $fd $fd_t) - ;; The desired file size. + ;;; The desired file size. (param $st_size $filesize_t) (result $error $errno_t) ) - ;; Adjust the timestamps of an open file or directory. - ;; Note: This is similar to `futimens` in POSIX. + ;;; Adjust the timestamps of an open file or directory. + ;;; Note: This is similar to `futimens` in POSIX. (@interface func (export "fd_filestat_set_times") (param $fd $fd_t) - ;; The desired values of the data access timestamp. + ;;; The desired values of the data access timestamp. (param $st_atim $timestamp_t) - ;; The desired values of the data modification timestamp. + ;;; The desired values of the data modification timestamp. (param $st_mtim $timestamp_t) - ;; A bitmask indicating which timestamps to adjust. + ;;; A bitmask indicating which timestamps to adjust. (param $fst_flags $fstflags_t) (result $error $errno_t) ) - ;; Read from a file descriptor, without using and updating the file descriptor's offset. - ;; Note: This is similar to `preadv` in POSIX. + ;;; Read from a file descriptor, without using and updating the file descriptor's offset. + ;;; Note: This is similar to `preadv` in POSIX. (@interface func (export "fd_pread") (param $fd $fd_t) - ;; List of scatter/gather vectors in which to store data. + ;;; List of scatter/gather vectors in which to store data. (param $iovs $iovec_t_array) - ;; The offset within the file at which to read. + ;;; The offset within the file at which to read. (param $offset $filesize_t) (result $error $errno_t) - ;; The number of bytes read. + ;;; The number of bytes read. (result $nread $size_t) ) - ;; Return a description of the given preopened file descriptor. + ;;; Return a description of the given preopened file descriptor. (@interface func (export "fd_prestat_get") (param $fd $fd_t) (result $error $errno_t) - ;; The buffer where the description is stored. + ;;; The buffer where the description is stored. (result $buf $prestat_t) ) - ;; Return a description of the given preopened file descriptor. + ;;; Return a description of the given preopened file descriptor. (@interface func (export "fd_prestat_dir_name") (param $fd $fd_t) - ;; A buffer into which to write the preopened directory name. + ;;; A buffer into which to write the preopened directory name. (param $path (@witx pointer u8)) (param $path_len $size_t) (result $error $errno_t) ) - ;; Write to a file descriptor, without using and updating the file descriptor's offset. - ;; Note: This is similar to `pwritev` in POSIX. + ;;; Write to a file descriptor, without using and updating the file descriptor's offset. + ;;; Note: This is similar to `pwritev` in POSIX. (@interface func (export "fd_pwrite") (param $fd $fd_t) - ;; List of scatter/gather vectors from which to retrieve data. + ;;; List of scatter/gather vectors from which to retrieve data. (param $iovs $ciovec_t_array) - ;; The offset within the file at which to write. + ;;; The offset within the file at which to write. (param $offset $filesize_t) (result $error $errno_t) - ;; The number of bytes written. + ;;; The number of bytes written. (result $nwritten $size_t) ) - ;; Read from a file descriptor. - ;; Note: This is similar to `readv` in POSIX. + ;;; Read from a file descriptor. + ;;; Note: This is similar to `readv` in POSIX. (@interface func (export "fd_read") (param $fd $fd_t) - ;; List of scatter/gather vectors to which to store data. + ;;; List of scatter/gather vectors to which to store data. (param $iovs $iovec_t_array) (result $error $errno_t) - ;; The number of bytes read. + ;;; The number of bytes read. (result $nread $size_t) ) - ;; Read directory entries from a directory. - ;; When successful, the contents of the output buffer consist of a sequence of - ;; directory entries. Each directory entry consists of a dirent_t object, - ;; followed by dirent_t::d_namlen bytes holding the name of the directory - ;; entry. + ;;; Read directory entries from a directory. + ;;; When successful, the contents of the output buffer consist of a sequence of + ;;; directory entries. Each directory entry consists of a dirent_t object, + ;;; followed by dirent_t::d_namlen bytes holding the name of the directory + ;;; entry. ;; - ;; This function fills the output buffer as much as possible, potentially - ;; truncating the last directory entry. This allows the caller to grow its - ;; read buffer size in case it's too small to fit a single large directory - ;; entry, or skip the oversized directory entry. + ;;; This function fills the output buffer as much as possible, potentially + ;;; truncating the last directory entry. This allows the caller to grow its + ;;; read buffer size in case it's too small to fit a single large directory + ;;; entry, or skip the oversized directory entry. (@interface func (export "fd_readdir") (param $fd $fd_t) - ;; The buffer where directory entries are stored + ;;; The buffer where directory entries are stored (param $buf (@witx pointer u8)) (param $buf_len $size_t) - ;; The location within the directory to start reading + ;;; The location within the directory to start reading (param $cookie $dircookie_t) (result $error $errno_t) - ;; The number of bytes stored in the read buffer. If less than the size of the read buffer, the end of the directory has been reached. + ;;; The number of bytes stored in the read buffer. If less than the size of the read buffer, the end of the directory has been reached. (result $bufused $size_t) ) - ;; Atomically replace a file descriptor by renumbering another file descriptor. + ;;; Atomically replace a file descriptor by renumbering another file descriptor. ;; - ;; Due to the strong focus on thread safety, this environment does not provide - ;; a mechanism to duplicate or renumber a file descriptor to an arbitrary - ;; number, like `dup2()`. This would be prone to race conditions, as an actual - ;; file descriptor with the same number could be allocated by a different - ;; thread at the same time. + ;;; Due to the strong focus on thread safety, this environment does not provide + ;;; a mechanism to duplicate or renumber a file descriptor to an arbitrary + ;;; number, like `dup2()`. This would be prone to race conditions, as an actual + ;;; file descriptor with the same number could be allocated by a different + ;;; thread at the same time. ;; - ;; This function provides a way to atomically renumber file descriptors, which - ;; would disappear if `dup2()` were to be removed entirely. + ;;; This function provides a way to atomically renumber file descriptors, which + ;;; would disappear if `dup2()` were to be removed entirely. (@interface func (export "fd_renumber") (param $fd $fd_t) - ;; The file descriptor to overwrite. + ;;; The file descriptor to overwrite. (param $to $fd_t) (result $error $errno_t) ) - ;; Move the offset of a file descriptor. - ;; Note: This is similar to `lseek` in POSIX. + ;;; Move the offset of a file descriptor. + ;;; Note: This is similar to `lseek` in POSIX. (@interface func (export "fd_seek") (param $fd $fd_t) - ;; The number of bytes to move. + ;;; The number of bytes to move. (param $offset $filedelta_t) - ;; The base from which the offset is relative. + ;;; The base from which the offset is relative. (param $whence $whence_t) (result $error $errno_t) - ;; The new offset of the file descriptor, relative to the start of the file. + ;;; The new offset of the file descriptor, relative to the start of the file. (result $newoffset $filesize_t) ) - ;; Synchronize the data and metadata of a file to disk. - ;; Note: This is similar to `fsync` in POSIX. + ;;; Synchronize the data and metadata of a file to disk. + ;;; Note: This is similar to `fsync` in POSIX. (@interface func (export "fd_sync") (param $fd $fd_t) (result $error $errno_t) ) - ;; Return the current offset of a file descriptor. - ;; Note: This is similar to `lseek(fd, 0, SEEK_CUR)` in POSIX. + ;;; Return the current offset of a file descriptor. + ;;; Note: This is similar to `lseek(fd, 0, SEEK_CUR)` in POSIX. (@interface func (export "fd_tell") (param $fd $fd_t) (result $error $errno_t) - ;; The current offset of the file descriptor, relative to the start of the file. + ;;; The current offset of the file descriptor, relative to the start of the file. (result $offset $filesize_t) ) - ;; Write to a file descriptor. - ;; Note: This is similar to `writev` in POSIX. + ;;; Write to a file descriptor. + ;;; Note: This is similar to `writev` in POSIX. (@interface func (export "fd_write") (param $fd $fd_t) - ;; List of scatter/gather vectors from which to retrieve data. + ;;; List of scatter/gather vectors from which to retrieve data. (param $iovs $ciovec_t_array) (result $error $errno_t) - ;; The number of bytes written. + ;;; The number of bytes written. (result $nwritten $size_t) ) - ;; Create a directory. - ;; Note: This is similar to `mkdirat` in POSIX. + ;;; Create a directory. + ;;; Note: This is similar to `mkdirat` in POSIX. (@interface func (export "path_create_directory") (param $fd $fd_t) - ;; The path at which to create the directory. + ;;; The path at which to create the directory. (param $path string) (result $error $errno_t) ) - ;; Return the attributes of a file or directory. - ;; Note: This is similar to `stat` in POSIX. + ;;; Return the attributes of a file or directory. + ;;; Note: This is similar to `stat` in POSIX. (@interface func (export "path_filestat_get") (param $fd $fd_t) - ;; Flags determining the method of how the path is resolved. + ;;; Flags determining the method of how the path is resolved. (param $flags $lookupflags_t) - ;; The path of the file or directory to inspect. + ;;; The path of the file or directory to inspect. (param $path string) (result $error $errno_t) - ;; The buffer where the file's attributes are stored. + ;;; The buffer where the file's attributes are stored. (result $buf $filestat_t) ) - ;; Adjust the timestamps of a file or directory. - ;; Note: This is similar to `utimensat` in POSIX. + ;;; Adjust the timestamps of a file or directory. + ;;; Note: This is similar to `utimensat` in POSIX. (@interface func (export "path_filestat_set_times") (param $fd $fd_t) - ;; Flags determining the method of how the path is resolved. + ;;; Flags determining the method of how the path is resolved. (param $flags $lookupflags_t) - ;; The path of the file or directory to operate on. + ;;; The path of the file or directory to operate on. (param $path string) - ;; The desired values of the data access timestamp. + ;;; The desired values of the data access timestamp. (param $st_atim $timestamp_t) - ;; The desired values of the data modification timestamp. + ;;; The desired values of the data modification timestamp. (param $st_mtim $timestamp_t) - ;; A bitmask indicating which timestamps to adjust. + ;;; A bitmask indicating which timestamps to adjust. (param $fst_flags $fstflags_t) (result $error $errno_t) ) - ;; Create a hard link. - ;; Note: This is similar to `linkat` in POSIX. + ;;; Create a hard link. + ;;; Note: This is similar to `linkat` in POSIX. (@interface func (export "path_link") (param $old_fd $fd_t) - ;; Flags determining the method of how the path is resolved. + ;;; Flags determining the method of how the path is resolved. (param $old_flags $lookupflags_t) - ;; The source path from which to link. + ;;; The source path from which to link. (param $old_path string) - ;; The working directory at which the resolution of the new path starts. + ;;; The working directory at which the resolution of the new path starts. (param $new_fd $fd_t) - ;; The destination path at which to create the hard link. + ;;; The destination path at which to create the hard link. (param $new_path string) (result $error $errno_t) ) - ;; Open a file or directory. + ;;; Open a file or directory. ;; - ;; The returned file descriptor is not guaranteed to be the lowest-numbered - ;; file 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 file descriptor is - ;; guaranteed to be less than 2**31. + ;;; The returned file descriptor is not guaranteed to be the lowest-numbered + ;;; file 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 file descriptor is + ;;; guaranteed to be less than 2**31. ;; - ;; Note: This is similar to `openat` in POSIX. + ;;; Note: This is similar to `openat` in POSIX. (@interface func (export "path_open") (param $fd $fd_t) - ;; Flags determining the method of how the path is resolved. + ;;; Flags determining the method of how the path is resolved. (param $dirflags $lookupflags_t) - ;; The relative path of the file or directory to open, relative to the - ;; `dirfd` directory. + ;;; The relative path of the file or directory to open, relative to the + ;;; `dirfd` directory. (param $path string) - ;; The method by which to open the file. + ;;; The method by which to open the file. (param $o_flags $oflags_t) - ;; The initial 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 initial 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 *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. (param $fs_rights_base $rights_t) (param $fs_rights_inherting $rights_t) (param $flags $fdflags_t) (result $error $errno_t) - ;; The file descriptor of the file that has been opened. + ;;; The file descriptor of the file that has been opened. (result $opened_fd $fd_t) ) - ;; Read the contents of a symbolic link. - ;; Note: This is similar to `readlinkat` in POSIX. + ;;; Read the contents of a symbolic link. + ;;; Note: This is similar to `readlinkat` in POSIX. (@interface func (export "path_readlink") (param $fd $fd_t) - ;; The path of the symbolic link from which to read. + ;;; The path of the symbolic link from which to read. (param $path string) - ;; The buffer to which to write the contents of the symbolic link. + ;;; The buffer to which to write the contents of the symbolic link. (param $buf (@witx pointer u8)) (param $buf_len $size_t) (result $error $errno_t) - ;; The number of bytes placed in the buffer. + ;;; The number of bytes placed in the buffer. (result $bufused $size_t) ) - ;; Remove a directory. - ;; Return `ENOTEMPTY` if the directory is not empty. - ;; Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX. + ;;; Remove a directory. + ;;; Return `ENOTEMPTY` if the directory is not empty. + ;;; Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX. (@interface func (export "path_remove_directory") (param $fd $fd_t) - ;; The path to a directory to remove. + ;;; The path to a directory to remove. (param $path string) (result $error $errno_t) ) - ;; Rename a file or directory. - ;; Note: This is similar to `renameat` in POSIX. + ;;; Rename a file or directory. + ;;; Note: This is similar to `renameat` in POSIX. (@interface func (export "path_rename") (param $fd $fd_t) - ;; The source path of the file or directory to rename. + ;;; The source path of the file or directory to rename. (param $old_path string) - ;; The working directory at which the resolution of the new path starts. + ;;; The working directory at which the resolution of the new path starts. (param $new_fd $fd_t) - ;; The destination path to which to rename the file or directory. + ;;; The destination path to which to rename the file or directory. (param $new_path string) (result $error $errno_t) ) - ;; Create a symbolic link. - ;; Note: This is similar to `symlinkat` in POSIX. + ;;; Create a symbolic link. + ;;; Note: This is similar to `symlinkat` in POSIX. (@interface func (export "path_symlink") - ;; The contents of the symbolic link. + ;;; The contents of the symbolic link. (param $old_path string) (param $fd $fd_t) - ;; The destination path at which to create the symbolic link. + ;;; The destination path at which to create the symbolic link. (param $new_path string) (result $error $errno_t) ) - ;; Unlink a file. - ;; Return `EISDIR` if the path refers to a directory. - ;; Note: This is similar to `unlinkat(fd, path, 0)` in POSIX. + ;;; Unlink a file. + ;;; Return `EISDIR` if the path refers to a directory. + ;;; Note: This is similar to `unlinkat(fd, path, 0)` in POSIX. (@interface func (export "path_unlink_file") (param $fd $fd_t) - ;; The path to a file to unlink. + ;;; The path to a file to unlink. (param $path string) (result $error $errno_t) ) - ;; Concurrently poll for the occurrence of a set of events. + ;;; Concurrently poll for the occurrence of a set of events. (@interface func (export "poll_oneoff") - ;; The events to which to subscribe. + ;;; The events to which to subscribe. (param $in (@witx const_pointer $subscription_t)) - ;; The events that have occurred. + ;;; The events that have occurred. (param $out (@witx pointer $event_t)) - ;; Both the number of subscriptions and events. + ;;; Both the number of subscriptions and events. (param $nsubscriptions $size_t) (result $error $errno_t) - ;; The number of events stored. + ;;; The number of events stored. (result $nevents $size_t) ) - ;; Terminate the process normally. An exit code of 0 indicates successful - ;; termination of the program. The meanings of other values is dependent on - ;; the environment. + ;;; Terminate the process normally. An exit code of 0 indicates successful + ;;; termination of the program. The meanings of other values is dependent on + ;;; the environment. (@interface func (export "proc_exit") - ;; The exit code returned by the process. + ;;; The exit code returned by the process. (param $rval $exitcode_t) ) - ;; Send a signal to the process of the calling thread. - ;; Note: This is similar to `raise` in POSIX. + ;;; Send a signal to the process of the calling thread. + ;;; Note: This is similar to `raise` in POSIX. (@interface func (export "proc_raise") - ;; The signal condition to trigger. + ;;; The signal condition to trigger. (param $sig $signal_t) (result $error $errno_t) ) - ;; Temporarily yield execution of the calling thread. - ;; Note: This is similar to `sched_yield` in POSIX. + ;;; Temporarily yield execution of the calling thread. + ;;; Note: This is similar to `sched_yield` in POSIX. (@interface func (export "sched_yield") (result $error $errno_t) ) - ;; Write high-quality random data into a buffer. - ;; This function blocks when the implementation is unable to immediately - ;; provide sufficient high-quality random data. - ;; This function may execute slowly, so when large mounts of random data are - ;; required, it's advisable to use this function to seed a pseudo-random - ;; number generator, rather than to provide the random data directly. + ;;; Write high-quality random data into a buffer. + ;;; This function blocks when the implementation is unable to immediately + ;;; provide sufficient high-quality random data. + ;;; This function may execute slowly, so when large mounts of random data are + ;;; required, it's advisable to use this function to seed a pseudo-random + ;;; number generator, rather than to provide the random data directly. (@interface func (export "random_get") - ;; The buffer to fill with random data. + ;;; The buffer to fill with random data. (param $buf (@witx pointer u8)) (param $buf_len $size_t) (result $error $errno_t) ) - ;; Receive a message from a socket. - ;; Note: This is similar to `recv` in POSIX, though it also supports reading - ;; the data into multiple buffers in the manner of `readv`. + ;;; Receive a message from a socket. + ;;; Note: This is similar to `recv` in POSIX, though it also supports reading + ;;; the data into multiple buffers in the manner of `readv`. (@interface func (export "sock_recv") (param $fd $fd_t) - ;; List of scatter/gather vectors to which to store data. + ;;; List of scatter/gather vectors to which to store data. (param $ri_data $iovec_t_array) - ;; Message flags. + ;;; Message flags. (param $ri_flags $riflags_t) (result $error $errno_t) - ;; Number of bytes stored in ri_data. + ;;; Number of bytes stored in ri_data. (result $ro_datalen $size_t) - ;; Message flags. + ;;; Message flags. (result $ro_flags $roflags_t) ) - ;; Send a message on a socket. - ;; Note: This is similar to `send` in POSIX, though it also supports writing - ;; the data from multiple buffers in the manner of `writev`. + ;;; Send a message on a socket. + ;;; Note: This is similar to `send` in POSIX, though it also supports writing + ;;; the data from multiple buffers in the manner of `writev`. (@interface func (export "sock_send") (param $fd $fd_t) - ;; List of scatter/gather vectors to which to retrieve data + ;;; List of scatter/gather vectors to which to retrieve data (param $si_data $ciovec_t_array) - ;; Message flags. + ;;; Message flags. (param $si_flags $siflags_t) (result $error $errno_t) - ;; Number of bytes transmitted. + ;;; Number of bytes transmitted. (result $so_datalen $size_t) ) - ;; Shut down socket send and receive channels. - ;; Note: This is similar to `shutdown` in POSIX. + ;;; Shut down socket send and receive channels. + ;;; Note: This is similar to `shutdown` in POSIX. (@interface func (export "sock_shutdown") (param $fd $fd_t) - ;; Which channels on the socket to shut down. + ;;; Which channels on the socket to shut down. (param $how $sdflags_t) (result $error $errno_t) ) diff --git a/tools/witx/src/ast.rs b/tools/witx/src/ast.rs index 62d5bf502..48c776ba9 100644 --- a/tools/witx/src/ast.rs +++ b/tools/witx/src/ast.rs @@ -120,6 +120,7 @@ pub enum DatatypeIdent { pub struct Datatype { pub name: Id, pub variant: DatatypeVariant, + pub docs: String, } #[derive(Debug, Clone, PartialEq, Eq)] @@ -149,14 +150,26 @@ pub enum IntRepr { pub struct EnumDatatype { pub name: Id, pub repr: IntRepr, - pub variants: Vec, + pub variants: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct EnumVariant { + pub name: Id, + pub docs: String, } #[derive(Debug, Clone, PartialEq, Eq)] pub struct FlagsDatatype { pub name: Id, pub repr: IntRepr, - pub flags: Vec, + pub flags: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct FlagsMember { + pub name: Id, + pub docs: String, } #[derive(Debug, Clone, PartialEq, Eq)] @@ -169,6 +182,7 @@ pub struct StructDatatype { pub struct StructMember { pub name: Id, pub type_: DatatypeIdent, + pub docs: String, } #[derive(Debug, Clone, PartialEq, Eq)] @@ -181,6 +195,7 @@ pub struct UnionDatatype { pub struct UnionVariant { pub name: Id, pub type_: DatatypeIdent, + pub docs: String, } #[derive(Debug, Clone)] @@ -188,6 +203,7 @@ pub struct Module { pub name: Id, definitions: Vec, entries: HashMap, + pub docs: String, } impl Module { @@ -195,11 +211,13 @@ impl Module { name: Id, definitions: Vec, entries: HashMap, + docs: String, ) -> Self { Module { name, definitions, entries, + docs, } } pub fn import(&self, name: &Id) -> Option> { @@ -275,6 +293,7 @@ impl PartialEq for ModuleEntry { pub struct ModuleImport { pub name: Id, pub variant: ModuleImportVariant, + pub docs: String, } #[derive(Debug, Clone, PartialEq, Eq)] @@ -287,6 +306,7 @@ pub struct InterfaceFunc { pub name: Id, pub params: Vec, pub results: Vec, + pub docs: String, } #[derive(Debug, Clone, PartialEq, Eq)] @@ -294,6 +314,7 @@ pub struct InterfaceFuncParam { pub name: Id, pub type_: DatatypeIdent, pub position: InterfaceFuncParamPosition, + pub docs: String, } #[derive(Debug, Clone, PartialEq, Eq)] diff --git a/tools/witx/src/docs.rs b/tools/witx/src/docs.rs new file mode 100644 index 000000000..532b3d902 --- /dev/null +++ b/tools/witx/src/docs.rs @@ -0,0 +1,227 @@ +use crate::ast::*; + +pub trait Documentation { + fn to_md(&self) -> String; +} + +impl Documentation for Document { + fn to_md(&self) -> String { + let mut ret = "# Types\n".to_string(); + for d in self.datatypes() { + ret += &d.to_md(); + } + + ret += "\n# Modules\n"; + for m in self.modules() { + ret += &m.to_md(); + } + ret + } +} + +impl BuiltinType { + fn name(&self) -> &'static str { + match self { + BuiltinType::String => "string", + BuiltinType::U8 => "u8", + BuiltinType::U16 => "u16", + BuiltinType::U32 => "u32", + BuiltinType::U64 => "u64", + BuiltinType::S8 => "s8", + BuiltinType::S16 => "s16", + BuiltinType::S32 => "s32", + BuiltinType::S64 => "s64", + BuiltinType::F32 => "f32", + BuiltinType::F64 => "f64", + } + } +} + +impl DatatypeIdent { + fn name(&self) -> String { + match self { + DatatypeIdent::Builtin(b) => b.name().to_string(), + DatatypeIdent::Array(a) => format!("Array<{}>", a.name()), + DatatypeIdent::Pointer(p) => format!("Pointer<{}>", p.name()), + DatatypeIdent::ConstPointer(p) => format!("ConstPointer<{}>", p.name()), + DatatypeIdent::Ident(i) => i.name.as_str().to_string(), + } + } +} + +impl Documentation for Datatype { + fn to_md(&self) -> String { + format!( + "## `{}`\n{}\n{}\n", + self.name.as_str(), + self.docs, + self.variant.to_md() + ) + } +} + +impl Documentation for DatatypeVariant { + fn to_md(&self) -> String { + match self { + DatatypeVariant::Alias(a) => a.to_md(), + DatatypeVariant::Enum(a) => a.to_md(), + DatatypeVariant::Flags(a) => a.to_md(), + DatatypeVariant::Struct(a) => a.to_md(), + DatatypeVariant::Union(a) => a.to_md(), + } + } +} + +impl Documentation for AliasDatatype { + fn to_md(&self) -> String { + format!("Alias to `{}`", self.to.name()) + } +} + +impl Documentation for EnumDatatype { + fn to_md(&self) -> String { + let variants = self + .variants + .iter() + .map(|v| format!("#### `{}`\n{}", v.name.as_str(), v.docs)) + .collect::>() + .join("\n"); + format!( + "Enum represented by `{}`\n\n### Variants:\n{}\n", + self.repr.name(), + variants + ) + } +} + +impl Documentation for FlagsDatatype { + fn to_md(&self) -> String { + let flags = self + .flags + .iter() + .map(|f| format!("#### `{}`\n{}\n", f.name.as_str(), f.docs)) + .collect::>() + .join("\n"); + format!( + "Flags represented by `{}`\n\n### Flags:\n{}", + self.repr.name(), + flags + ) + } +} + +impl Documentation for StructDatatype { + fn to_md(&self) -> String { + let members = self + .members + .iter() + .map(|m| { + format!( + "#### `{}`\nMember type: `{}`\n{}", + m.name.as_str(), + m.type_.name(), + m.docs, + ) + }) + .collect::>() + .join("\n"); + format!("### Struct members:\n{}", members) + } +} + +impl Documentation for UnionDatatype { + fn to_md(&self) -> String { + let variants = self + .variants + .iter() + .map(|v| { + format!( + "#### `{}`\nVariant type: `{}`\n{}", + v.name.as_str(), + v.type_.name(), + v.docs, + ) + }) + .collect::>() + .join("\n"); + format!("### Union variants:\n{}\n", variants) + } +} + +impl IntRepr { + fn name(&self) -> &'static str { + match self { + IntRepr::U8 => "u8", + IntRepr::U16 => "u16", + IntRepr::U32 => "u32", + IntRepr::U64 => "u64", + } + } +} + +impl Documentation for Module { + fn to_md(&self) -> String { + let imports = self + .imports() + .map(|i| i.to_md()) + .collect::>() + .join("\n"); + let funcs = self + .funcs() + .map(|i| i.to_md()) + .collect::>() + .join("\n"); + format!( + "## `{}`\n### Imports\n{}\n### Functions\n{}", + self.name.as_str(), + imports, + funcs, + ) + } +} + +impl Documentation for ModuleImport { + fn to_md(&self) -> String { + match self.variant { + ModuleImportVariant::Memory => format!("* {}: Memory", self.name.as_str()), + } + } +} + +impl Documentation for InterfaceFunc { + fn to_md(&self) -> String { + let params = self + .params + .iter() + .map(|f| { + format!( + "##### `{name}`\n`{name}` has type `{type_}`\n{docs}", + name = f.name.as_str(), + type_ = f.type_.name(), + docs = f.docs + ) + }) + .collect::>() + .join("\n"); + let results = self + .results + .iter() + .map(|f| { + format!( + "##### `{name}`\n`{name}` has type `{type_}`\n{docs}", + name = f.name.as_str(), + type_ = f.type_.name(), + docs = f.docs + ) + }) + .collect::>() + .join("\n"); + format!( + "### {}\n{}\n#### Parameters:\n{}#### Results:\n{}", + self.name.as_str(), + self.docs, + params, + results, + ) + } +} diff --git a/tools/witx/src/lib.rs b/tools/witx/src/lib.rs index 3c2d945ec..60b0e0663 100644 --- a/tools/witx/src/lib.rs +++ b/tools/witx/src/lib.rs @@ -2,6 +2,8 @@ mod ast; /// Map witx types to core (wasm standard) types mod coretypes; +/// Render documentation +mod docs; /// Interface for filesystem or mock IO mod io; /// Witx syntax parsing from SExprs @@ -15,11 +17,12 @@ mod validate; pub use ast::{ AliasDatatype, BuiltinType, Datatype, DatatypeIdent, DatatypeVariant, Definition, Document, - Entry, EnumDatatype, FlagsDatatype, Id, IntRepr, InterfaceFunc, InterfaceFuncParam, - InterfaceFuncParamPosition, Module, ModuleDefinition, ModuleEntry, ModuleImport, - ModuleImportVariant, StructDatatype, StructMember, UnionDatatype, UnionVariant, + Entry, EnumDatatype, EnumVariant, FlagsDatatype, FlagsMember, Id, IntRepr, InterfaceFunc, + InterfaceFuncParam, InterfaceFuncParamPosition, Module, ModuleDefinition, ModuleEntry, + ModuleImport, ModuleImportVariant, StructDatatype, StructMember, UnionDatatype, UnionVariant, }; pub use coretypes::{AtomType, CoreFuncType, CoreParamSignifies, CoreParamType, DatatypePassedBy}; +pub use docs::Documentation; pub use io::{Filesystem, MockFs, WitxIo}; pub use parser::DeclSyntax; pub use render::{Render, SExpr as RenderSExpr}; diff --git a/tools/witx/src/main.rs b/tools/witx/src/main.rs index 8b1cab6ea..6251c3efa 100644 --- a/tools/witx/src/main.rs +++ b/tools/witx/src/main.rs @@ -1,12 +1,14 @@ -use clap::{App, Arg}; +use clap::{App, Arg, SubCommand}; +use std::fs::File; +use std::io::Write; use std::path::PathBuf; use std::process; -use witx::load; +use witx::{load, Documentation}; pub fn main() { let app = App::new("witx") .version(env!("CARGO_PKG_VERSION")) - .about("Validate witx file format") + .about("Validate and process witx files") .arg( Arg::with_name("input") .required(true) @@ -20,6 +22,17 @@ pub fn main() { .takes_value(false) .required(false), ) + .subcommand( + SubCommand::with_name("docs") + .about("Output documentation") + .arg( + Arg::with_name("output") + .short("o") + .long("output") + .takes_value(true) + .required(false), + ), + ) .get_matches(); let inputs = app @@ -34,6 +47,16 @@ pub fn main() { if app.is_present("verbose") { println!("{:?}", doc) } + + if let Some(subcommand) = app.subcommand_matches("docs") { + let md = doc.to_md(); + if let Some(output) = subcommand.value_of("output") { + let mut file = File::create(output).expect("create output file"); + file.write_all(md.as_bytes()).expect("write output file"); + } else { + println!("{}", md) + } + } } Err(e) => { println!("{}", e.report()); diff --git a/tools/witx/src/parser.rs b/tools/witx/src/parser.rs index 9e699267e..77a1c0b03 100644 --- a/tools/witx/src/parser.rs +++ b/tools/witx/src/parser.rs @@ -1,3 +1,4 @@ +use wast::lexer::Comment; use wast::parser::{Cursor, Parse, Parser, Peek, Result}; ///! Parser turns s-expressions into unvalidated syntax constructs. @@ -96,6 +97,86 @@ impl Parse<'_> for BuiltinType { } } +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct CommentSyntax<'a> { + pub comments: Vec<&'a str>, +} + +impl<'a> Parse<'a> for CommentSyntax<'a> { + fn parse(parser: Parser<'a>) -> Result> { + let comments = parser.step(|mut cursor| { + let mut comments = Vec::new(); + loop { + let (comment, c) = match cursor.comment() { + Some(pair) => pair, + None => break, + }; + cursor = c; + comments.push(match comment { + Comment::Block(s) => &s[2..s.len() - 2], + Comment::Line(s) => &s[2..], + }); + } + Ok((comments, cursor)) + })?; + Ok(CommentSyntax { comments }) + } +} + +impl<'a> CommentSyntax<'a> { + pub fn docs(&self) -> String { + // Perform a small amount of preprocessing by removing all trailing + // whitespace, and then also filter for only "doc comments" which are `;;;` + // or `(;; ... ;)`. + let docs = self + .comments + .iter() + .map(|d| d.trim_end()) + .filter_map(|d| { + if d.starts_with(";") { + Some(&d[1..]) + } else { + None + } + }) + .collect::>(); + + // Figure out how much leading whitespace we're going to be trimming from + // all docs, trimming the minimum amount in each doc comment. + let to_trim = docs + .iter() + .filter(|d| !d.is_empty()) + .map(|d| d.len() - d.trim().len()) + .min() + .unwrap_or(0); + + // Separate all documents by a newline and collect everything into a single + // string. + let mut ret = String::new(); + for doc in docs { + if !doc.is_empty() { + ret.push_str(doc[to_trim..].trim_end()); + } + ret.push_str("\n"); + } + return ret; + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct Documented<'a, T> { + pub comments: CommentSyntax<'a>, + pub item: T, +} + +impl<'a, T: Parse<'a>> Parse<'a> for Documented<'a, T> { + fn parse(parser: Parser<'a>) -> Result { + let comments = parser.parse()?; + let item = parser.parse()?; + Ok(Documented { comments, item }) + } +} + #[derive(Debug, Clone, PartialEq, Eq)] pub enum DatatypeIdentSyntax<'a> { Builtin(BuiltinType), @@ -179,14 +260,14 @@ impl Peek for AtInterface { #[derive(Debug, Clone, PartialEq, Eq)] pub struct TopLevelDocument<'a> { - pub items: Vec>, + pub items: Vec>>, } impl<'a> Parse<'a> for TopLevelDocument<'a> { fn parse(parser: Parser<'a>) -> Result { let mut items = Vec::new(); while !parser.is_empty() { - items.push(parser.parens(|p| p.parse())?); + items.push(parser.parse()?); } Ok(TopLevelDocument { items }) } @@ -200,12 +281,14 @@ pub enum TopLevelSyntax<'a> { impl<'a> Parse<'a> for TopLevelSyntax<'a> { fn parse(parser: Parser<'a>) -> Result { - if parser.peek::() { - parser.parse::()?; - Ok(TopLevelSyntax::Use(parser.parse()?)) - } else { - Ok(TopLevelSyntax::Decl(parser.parse()?)) - } + parser.parens(|p| { + if p.peek::() { + p.parse::()?; + Ok(TopLevelSyntax::Use(p.parse()?)) + } else { + Ok(TopLevelSyntax::Decl(p.parse()?)) + } + }) } } @@ -278,7 +361,7 @@ impl<'a> Parse<'a> for TypedefSyntax<'a> { #[derive(Debug, Clone, PartialEq, Eq)] pub struct EnumSyntax<'a> { pub repr: BuiltinType, - pub members: Vec>, + pub members: Vec>>, } impl<'a> Parse<'a> for EnumSyntax<'a> { @@ -297,7 +380,7 @@ impl<'a> Parse<'a> for EnumSyntax<'a> { #[derive(Debug, Clone, PartialEq, Eq)] pub struct FlagsSyntax<'a> { pub repr: BuiltinType, - pub flags: Vec>, + pub flags: Vec>>, } impl<'a> Parse<'a> for FlagsSyntax<'a> { @@ -314,16 +397,16 @@ impl<'a> Parse<'a> for FlagsSyntax<'a> { #[derive(Debug, Clone, PartialEq, Eq)] pub struct StructSyntax<'a> { - pub fields: Vec>, + pub fields: Vec>>, } impl<'a> Parse<'a> for StructSyntax<'a> { fn parse(parser: Parser<'a>) -> Result { parser.parse::()?; let mut fields = Vec::new(); - fields.push(parser.parens(|p| p.parse())?); + fields.push(parser.parse()?); while !parser.is_empty() { - fields.push(parser.parens(|p| p.parse())?); + fields.push(parser.parse()?); } Ok(StructSyntax { fields }) } @@ -337,25 +420,27 @@ pub struct FieldSyntax<'a> { impl<'a> Parse<'a> for FieldSyntax<'a> { fn parse(parser: Parser<'a>) -> Result { - parser.parse::()?; - let name = parser.parse()?; - let type_ = parser.parse()?; - Ok(FieldSyntax { name, type_ }) + parser.parens(|p| { + p.parse::()?; + let name = p.parse()?; + let type_ = p.parse()?; + Ok(FieldSyntax { name, type_ }) + }) } } #[derive(Debug, Clone, PartialEq, Eq)] pub struct UnionSyntax<'a> { - pub fields: Vec>, + pub fields: Vec>>, } impl<'a> Parse<'a> for UnionSyntax<'a> { fn parse(parser: Parser<'a>) -> Result { parser.parse::()?; let mut fields = Vec::new(); - fields.push(parser.parens(|p| p.parse())?); + fields.push(parser.parse()?); while !parser.is_empty() { - fields.push(parser.parens(|p| p.parse())?); + fields.push(parser.parse()?); } Ok(UnionSyntax { fields }) } @@ -364,7 +449,7 @@ impl<'a> Parse<'a> for UnionSyntax<'a> { #[derive(Debug, Clone, PartialEq, Eq)] pub struct ModuleSyntax<'a> { pub name: wast::Id<'a>, - pub decls: Vec>, + pub decls: Vec>>, } impl<'a> Parse<'a> for ModuleSyntax<'a> { @@ -373,7 +458,7 @@ impl<'a> Parse<'a> for ModuleSyntax<'a> { let name = parser.parse()?; let mut decls = Vec::new(); while !parser.is_empty() { - decls.push(parser.parens(|p| p.parse())?); + decls.push(parser.parse()?); } Ok(ModuleSyntax { name, decls }) } @@ -387,14 +472,16 @@ pub enum ModuleDeclSyntax<'a> { impl<'a> Parse<'a> for ModuleDeclSyntax<'a> { fn parse(parser: Parser<'a>) -> Result { - let mut l = parser.lookahead1(); - if l.peek::() { - Ok(ModuleDeclSyntax::Import(parser.parse()?)) - } else if l.peek::() { - Ok(ModuleDeclSyntax::Func(parser.parse()?)) - } else { - Err(l.error()) - } + parser.parens(|p| { + let mut l = p.lookahead1(); + if l.peek::() { + Ok(ModuleDeclSyntax::Import(p.parse()?)) + } else if l.peek::() { + Ok(ModuleDeclSyntax::Func(p.parse()?)) + } else { + Err(l.error()) + } + }) } } @@ -442,8 +529,8 @@ impl Parse<'_> for ImportTypeSyntax { pub struct InterfaceFuncSyntax<'a> { pub export: &'a str, pub export_loc: wast::Span, - pub params: Vec>, - pub results: Vec>, + pub params: Vec>>, + pub results: Vec>>, } impl<'a> Parse<'a> for InterfaceFuncSyntax<'a> { @@ -460,25 +547,21 @@ impl<'a> Parse<'a> for InterfaceFuncSyntax<'a> { let mut results = Vec::new(); while !parser.is_empty() { - parser.parens(|p| { - let mut l = p.lookahead1(); - if l.peek::() { - parser.parse::()?; - params.push(FieldSyntax { - name: parser.parse()?, - type_: parser.parse()?, + let func_field = parser.parse::>()?; + match func_field.item { + InterfaceFuncField::Param(item) => { + params.push(Documented { + comments: func_field.comments, + item, }); - } else if l.peek::() { - parser.parse::()?; - results.push(FieldSyntax { - name: parser.parse()?, - type_: parser.parse()?, + } + InterfaceFuncField::Result(item) => { + results.push(Documented { + comments: func_field.comments, + item, }); - } else { - return Err(l.error()); } - Ok(()) - })?; + } } Ok(InterfaceFuncSyntax { @@ -490,6 +573,33 @@ impl<'a> Parse<'a> for InterfaceFuncSyntax<'a> { } } +enum InterfaceFuncField<'a> { + Param(FieldSyntax<'a>), + Result(FieldSyntax<'a>), +} +impl<'a> Parse<'a> for InterfaceFuncField<'a> { + fn parse(parser: Parser<'a>) -> Result { + parser.parens(|p| { + let mut l = p.lookahead1(); + if l.peek::() { + parser.parse::()?; + Ok(InterfaceFuncField::Param(FieldSyntax { + name: parser.parse()?, + type_: parser.parse()?, + })) + } else if l.peek::() { + parser.parse::()?; + Ok(InterfaceFuncField::Result(FieldSyntax { + name: parser.parse()?, + type_: parser.parse()?, + })) + } else { + Err(l.error()) + } + }) + } +} + impl PartialEq for InterfaceFuncSyntax<'_> { fn eq(&self, other: &InterfaceFuncSyntax<'_>) -> bool { // skip the `export_loc` field diff --git a/tools/witx/src/render.rs b/tools/witx/src/render.rs index 8e23a5fa8..4bb7df729 100644 --- a/tools/witx/src/render.rs +++ b/tools/witx/src/render.rs @@ -21,6 +21,8 @@ pub enum SExpr { Quote(String), /// Short for Annotation Annot(String), + /// Doc comment + Docs(String, Box), } impl fmt::Display for SExpr { @@ -39,6 +41,7 @@ impl fmt::Display for SExpr { SExpr::Ident(i) => write!(f, "${}", i), SExpr::Quote(q) => write!(f, "\"{}\"", q), SExpr::Annot(a) => write!(f, "@{}", a), + SExpr::Docs(d, s) => write!(f, "(;; {} ;) {}", d, s), } } } @@ -56,6 +59,13 @@ impl SExpr { fn annot(s: &str) -> SExpr { SExpr::Annot(s.to_string()) } + fn docs(d: &str, s: SExpr) -> SExpr { + if d.is_empty() { + s + } else { + SExpr::Docs(d.to_string(), Box::new(s)) + } + } } pub trait Render { @@ -110,7 +120,10 @@ impl Render for Datatype { fn to_sexpr(&self) -> SExpr { let name = self.name.to_sexpr(); let body = self.variant.to_sexpr(); - SExpr::Vec(vec![SExpr::word("typename"), name, body]) + SExpr::docs( + &self.docs, + SExpr::Vec(vec![SExpr::word("typename"), name, body]), + ) } } @@ -138,7 +151,7 @@ impl Render for EnumDatatype { let variants = self .variants .iter() - .map(|v| v.to_sexpr()) + .map(|v| SExpr::docs(&v.docs, v.name.to_sexpr())) .collect::>(); SExpr::Vec([header, variants].concat()) } @@ -150,7 +163,7 @@ impl Render for FlagsDatatype { let flags = self .flags .iter() - .map(|f| f.to_sexpr()) + .map(|f| SExpr::docs(&f.docs, f.name.to_sexpr())) .collect::>(); SExpr::Vec([header, flags].concat()) } @@ -163,11 +176,14 @@ impl Render for StructDatatype { .members .iter() .map(|m| { - SExpr::Vec(vec![ - SExpr::word("field"), - m.name.to_sexpr(), - m.type_.to_sexpr(), - ]) + SExpr::docs( + &m.docs, + SExpr::Vec(vec![ + SExpr::word("field"), + m.name.to_sexpr(), + m.type_.to_sexpr(), + ]), + ) }) .collect::>(); SExpr::Vec([header, members].concat()) @@ -181,11 +197,14 @@ impl Render for UnionDatatype { .variants .iter() .map(|v| { - SExpr::Vec(vec![ - SExpr::word("field"), - v.name.to_sexpr(), - v.type_.to_sexpr(), - ]) + SExpr::docs( + &v.docs, + SExpr::Vec(vec![ + SExpr::word("field"), + v.name.to_sexpr(), + v.type_.to_sexpr(), + ]), + ) }) .collect::>(); SExpr::Vec([header, variants].concat()) @@ -211,7 +230,7 @@ impl Render for Module { .map(|i| i.to_sexpr()) .chain(self.funcs().map(|f| f.to_sexpr())) .collect::>(); - SExpr::Vec([header, definitions].concat()) + SExpr::docs(&self.docs, SExpr::Vec([header, definitions].concat())) } } @@ -220,11 +239,14 @@ impl Render for ModuleImport { let variant = match self.variant { ModuleImportVariant::Memory => SExpr::Vec(vec![SExpr::word("memory")]), }; - SExpr::Vec(vec![ - SExpr::word("import"), - SExpr::quote(self.name.as_str()), - variant, - ]) + SExpr::docs( + &self.docs, + SExpr::Vec(vec![ + SExpr::word("import"), + SExpr::quote(self.name.as_str()), + variant, + ]), + ) } } @@ -242,24 +264,30 @@ impl Render for InterfaceFunc { .params .iter() .map(|f| { - SExpr::Vec(vec![ - SExpr::word("param"), - f.name.to_sexpr(), - f.type_.to_sexpr(), - ]) + SExpr::docs( + &f.docs, + SExpr::Vec(vec![ + SExpr::word("param"), + f.name.to_sexpr(), + f.type_.to_sexpr(), + ]), + ) }) .collect(); let results = self .results .iter() .map(|f| { - SExpr::Vec(vec![ - SExpr::word("result"), - f.name.to_sexpr(), - f.type_.to_sexpr(), - ]) + SExpr::docs( + &f.docs, + SExpr::Vec(vec![ + SExpr::word("result"), + f.name.to_sexpr(), + f.type_.to_sexpr(), + ]), + ) }) .collect(); - SExpr::Vec([header, params, results].concat()) + SExpr::docs(&self.docs, SExpr::Vec([header, params, results].concat())) } } diff --git a/tools/witx/src/toplevel.rs b/tools/witx/src/toplevel.rs index 281ad4757..2e0738a6b 100644 --- a/tools/witx/src/toplevel.rs +++ b/tools/witx/src/toplevel.rs @@ -58,11 +58,11 @@ fn parse_file( let doc = wast::parser::parse::(&buf).map_err(adjust_err)?; for t in doc.items { - match t { + match t.item { TopLevelSyntax::Decl(d) => { let def = validator .scope(&input, &path) - .validate_decl(&d) + .validate_decl(&d, &t.comments) .map_err(WitxError::Validation)?; definitions.push(def); } diff --git a/tools/witx/src/validate.rs b/tools/witx/src/validate.rs index a0d9ea96b..eba087e8c 100644 --- a/tools/witx/src/validate.rs +++ b/tools/witx/src/validate.rs @@ -1,13 +1,14 @@ use crate::{ io::{Filesystem, WitxIo}, parser::{ - DatatypeIdentSyntax, DeclSyntax, EnumSyntax, FlagsSyntax, ImportTypeSyntax, - ModuleDeclSyntax, StructSyntax, TypedefSyntax, UnionSyntax, + CommentSyntax, DatatypeIdentSyntax, DeclSyntax, Documented, EnumSyntax, FlagsSyntax, + ImportTypeSyntax, ModuleDeclSyntax, StructSyntax, TypedefSyntax, UnionSyntax, }, AliasDatatype, BuiltinType, Datatype, DatatypeIdent, DatatypePassedBy, DatatypeVariant, - Definition, Entry, EnumDatatype, FlagsDatatype, Id, IntRepr, InterfaceFunc, InterfaceFuncParam, - InterfaceFuncParamPosition, Location, Module, ModuleDefinition, ModuleEntry, ModuleImport, - ModuleImportVariant, StructDatatype, StructMember, UnionDatatype, UnionVariant, + Definition, Entry, EnumDatatype, EnumVariant, FlagsDatatype, FlagsMember, Id, IntRepr, + InterfaceFunc, InterfaceFuncParam, InterfaceFuncParamPosition, Location, Module, + ModuleDefinition, ModuleEntry, ModuleImport, ModuleImportVariant, StructDatatype, StructMember, + UnionDatatype, UnionVariant, }; use failure::Fail; use std::collections::HashMap; @@ -158,10 +159,15 @@ impl DocValidationScope<'_> { self.doc.scope.get(name.name(), loc) } - pub fn validate_decl(&mut self, decl: &DeclSyntax) -> Result { + pub fn validate_decl( + &mut self, + decl: &DeclSyntax, + comments: &CommentSyntax, + ) -> Result { match decl { DeclSyntax::Typename(decl) => { let name = self.introduce(&decl.ident)?; + let docs = comments.docs(); let variant = match &decl.def { TypedefSyntax::Ident(syntax) => DatatypeVariant::Alias(AliasDatatype { @@ -186,6 +192,7 @@ impl DocValidationScope<'_> { let rc_datatype = Rc::new(Datatype { name: name.clone(), variant, + docs, }); self.doc .entries @@ -205,6 +212,7 @@ impl DocValidationScope<'_> { name.clone(), definitions, module_validator.entries, + comments.docs(), )); self.doc .entries @@ -261,8 +269,12 @@ impl DocValidationScope<'_> { let variants = syntax .members .iter() - .map(|i| enum_scope.introduce(i.name(), self.location(i.span()))) - .collect::, _>>()?; + .map(|i| { + let name = enum_scope.introduce(i.item.name(), self.location(i.item.span()))?; + let docs = i.comments.docs(); + Ok(EnumVariant { name, docs }) + }) + .collect::, _>>()?; Ok(EnumDatatype { name: name.clone(), @@ -282,8 +294,12 @@ impl DocValidationScope<'_> { let flags = syntax .flags .iter() - .map(|i| flags_scope.introduce(i.name(), self.location(i.span()))) - .collect::, _>>()?; + .map(|i| { + let name = flags_scope.introduce(i.item.name(), self.location(i.item.span()))?; + let docs = i.comments.docs(); + Ok(FlagsMember { name, docs }) + }) + .collect::, _>>()?; Ok(FlagsDatatype { name: name.clone(), @@ -303,10 +319,11 @@ impl DocValidationScope<'_> { .fields .iter() .map(|f| { - Ok(StructMember { - name: member_scope.introduce(f.name.name(), self.location(f.name.span()))?, - type_: self.validate_datatype_ident(&f.type_)?, - }) + let name = member_scope + .introduce(f.item.name.name(), self.location(f.item.name.span()))?; + let type_ = self.validate_datatype_ident(&f.item.type_)?; + let docs = f.comments.docs(); + Ok(StructMember { name, type_, docs }) }) .collect::, _>>()?; @@ -327,10 +344,11 @@ impl DocValidationScope<'_> { .fields .iter() .map(|f| { - Ok(UnionVariant { - name: variant_scope.introduce(f.name.name(), self.location(f.name.span()))?, - type_: self.validate_datatype_ident(&f.type_)?, - }) + let name = variant_scope + .introduce(f.item.name.name(), self.location(f.item.name.span()))?; + let type_ = self.validate_datatype_ident(&f.item.type_)?; + let docs = f.comments.docs(); + Ok(UnionVariant { name, type_, docs }) }) .collect::, _>>()?; @@ -375,9 +393,9 @@ impl<'a> ModuleValidation<'a> { fn validate_decl( &mut self, - decl: &ModuleDeclSyntax, + decl: &Documented, ) -> Result { - match decl { + match &decl.item { ModuleDeclSyntax::Import(syntax) => { let loc = self.doc.location(syntax.name_loc); let name = self.scope.introduce(syntax.name, loc)?; @@ -387,6 +405,7 @@ impl<'a> ModuleValidation<'a> { let rc_import = Rc::new(ModuleImport { name: name.clone(), variant, + docs: decl.comments.docs(), }); self.entries .insert(name, ModuleEntry::Import(Rc::downgrade(&rc_import))); @@ -402,10 +421,13 @@ impl<'a> ModuleValidation<'a> { .enumerate() .map(|(ix, f)| { Ok(InterfaceFuncParam { - name: argnames - .introduce(f.name.name(), self.doc.location(f.name.span()))?, - type_: self.doc.validate_datatype_ident(&f.type_)?, + name: argnames.introduce( + f.item.name.name(), + self.doc.location(f.item.name.span()), + )?, + type_: self.doc.validate_datatype_ident(&f.item.type_)?, position: InterfaceFuncParamPosition::Param(ix), + docs: f.comments.docs(), }) }) .collect::, _>>()?; @@ -414,20 +436,23 @@ impl<'a> ModuleValidation<'a> { .iter() .enumerate() .map(|(ix, f)| { - let type_ = self.doc.validate_datatype_ident(&f.type_)?; + let type_ = self.doc.validate_datatype_ident(&f.item.type_)?; if ix == 0 { match type_.passed_by() { DatatypePassedBy::Value(_) => {} _ => Err(ValidationError::InvalidFirstResultType { - location: self.doc.location(f.name.span()), + location: self.doc.location(f.item.name.span()), })?, } } Ok(InterfaceFuncParam { - name: argnames - .introduce(f.name.name(), self.doc.location(f.name.span()))?, + name: argnames.introduce( + f.item.name.name(), + self.doc.location(f.item.name.span()), + )?, type_, position: InterfaceFuncParamPosition::Result(ix), + docs: f.comments.docs(), }) }) .collect::, _>>()?; @@ -436,6 +461,7 @@ impl<'a> ModuleValidation<'a> { name: name.clone(), params, results, + docs: decl.comments.docs(), }); self.entries .insert(name, ModuleEntry::Func(Rc::downgrade(&rc_func))); diff --git a/tools/witx/tests/wasi.rs b/tools/witx/tests/wasi.rs index b5a9d527c..aef954236 100644 --- a/tools/witx/tests/wasi.rs +++ b/tools/witx/tests/wasi.rs @@ -29,5 +29,31 @@ fn render_roundtrip() { .map_err(|e| e.report_with(&witx::MockFs::new(&[("-", &back_to_sexprs)]))) .unwrap(); + let back_to_sexprs = format!("{}", doc); + + let doc2 = witx::parse(&back_to_sexprs) + .map_err(|e| e.report_with(&witx::MockFs::new(&[("-", &back_to_sexprs)]))) + .unwrap(); + + // I'd just assert_eq, but when it fails the debug print is thousands of lines long and impossible + // to figure out where they are unequal. + if doc != doc2 { + for type_ in doc.datatypes() { + let type2 = doc2.datatype(&type_.name).expect("doc2 missing datatype"); + assert_eq!(type_, type2); + } + for mod_ in doc.modules() { + let mod2 = doc2.module(&mod_.name).expect("doc2 missing module"); + for import in mod_.imports() { + let import2 = mod2.import(&import.name).expect("mod2 missing import"); + assert_eq!(import, import2); + } + for func in mod_.funcs() { + let func2 = mod2.func(&func.name).expect("mod2 missing func"); + assert_eq!(func, func2); + } + } + } + // This should be equivelant to the above, but just in case some code changes where it isnt: assert_eq!(doc, doc2); }