;; WASI Filesystem Path API.
;;
;; Some content here is derived from [CloudABI](https://github.com/NuxiNL/cloudabi).
;;
;; This is a `witx` file. See [here](https://github.com/WebAssembly/WASI/tree/master/docs/witx.md)
;; for an explanation of what that means.

(use "typenames.witx")

(module $wasi_ephemeral_path
  ;;; Linear memory to be accessed by WASI functions that need it.
  (import "memory" (memory))

  ;;; Create a directory.
  ;;; Note: This is similar to `mkdirat` in POSIX.
  (@interface func (export "create_directory")
    (param $fd $fd)
    ;;; The path at which to create the directory.
    (param $path string)
    (result $error $errno)
  )

  ;;; Return the attributes of a file or directory.
  ;;; Note: This is similar to `stat` in POSIX.
  (@interface func (export "filestat_get")
    (param $fd $fd)
    ;;; Flags determining the method of how the path is resolved.
    (param $flags $lookupflags)
    ;;; The path of the file or directory to inspect.
    (param $path string)
    (result $error $errno)
    ;;; The buffer where the file's attributes are stored.
    (result $buf $filestat)
  )

  ;;; Adjust the timestamps of a file or directory.
  ;;; Note: This is similar to `utimensat` in POSIX.
  (@interface func (export "filestat_set_times")
    (param $fd $fd)
    ;;; Flags determining the method of how the path is resolved.
    (param $flags $lookupflags)
    ;;; The path of the file or directory to operate on.
    (param $path string)
    ;;; The desired values of the data access timestamp.
    (param $atim $timestamp)
    ;;; The desired values of the data modification timestamp.
    (param $mtim $timestamp)
    ;;; A bitmask indicating which timestamps to adjust.
    (param $fst_flags $fstflags)
    (result $error $errno)
  )

  ;;; Set the permissions of a file or directory.
  ;;;
  ;;; This sets the permissions associated with a file or directory in
  ;;; a filesystem at the time it is called. The ability to actually access
  ;;; a file or directory may depend on additional permissions not reflected
  ;;; here.
  ;;;
  ;;; Note: This is similar to `fchmodat` in POSIX.
  ;;;
  ;;; Unlike POSIX, this doesn't expose a user/group/other distinction;
  ;;; implementations in POSIX environments are suggested to consult the
  ;;; umask to determine which of the user/group/other flags to modify.
  (@interface func (export "permissions_set")
    (param $fd $fd)
    ;;; Flags determining the method of how the path is resolved.
    (param $flags $lookupflags)
    ;;; The path to a file to query.
    (param $path string)
    ;;; The permissions to associate with the file.
    (param $permissions $permissions)
    (result $error $errno)
  )

  ;;; Create a hard link.
  ;;; Note: This is similar to `linkat` in POSIX.
  (@interface func (export "link")
    (param $old_fd $fd)
    ;;; Flags determining the method of how the path is resolved.
    (param $old_flags $lookupflags)
    ;;; The source path from which to link.
    (param $old_path string)
    ;;; The working directory at which the resolution of the new path starts.
    (param $new_fd $fd)
    ;;; The destination path at which to create the hard link.
    (param $new_path string)
    (result $error $errno)
  )

  ;;; 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.
  ;;
  ;;; Note: This is similar to `openat` in POSIX.
  (@interface func (export "open")
    (param $fd $fd)
    ;;; Flags determining the method of how the path is resolved.
    (param $dirflags $lookupflags)
    ;;; The relative path of the file or directory to open, relative to the
    ;;; `fd` directory.
    (param $path string)
    ;;; The method by which to open the file.
    (param $oflags $oflags)
    ;;; 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.
    (param $fs_rights_base $rights)
    (param $fs_rights_inherting $rights)
    (param $fdflags $fdflags)
    ;;; If a file is created, the filesystem permissions to associate with it.
    (param $permissions $permissions)
    (result $error $errno)
    ;;; The file descriptor of the file that has been opened.
    (result $opened_fd $fd)
  )

  ;;; Read the contents of a symbolic link.
  ;;; Note: This is similar to `readlinkat` in POSIX.
  (@interface func (export "readlink")
    (param $fd $fd)
    ;;; 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.
    (param $buf (@witx pointer char8))
    (param $buf_len $size)
    (result $error $errno)
    ;;; The number of bytes placed in the buffer.
    (result $bufused $size)
  )

  ;;; Remove a directory.
  ;;; Return `errno::notempty` if the directory is not empty.
  ;;; Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX.
  (@interface func (export "remove_directory")
    (param $fd $fd)
    ;;; The path to a directory to remove.
    (param $path string)
    (result $error $errno)
  )

  ;;; Rename a file or directory.
  ;;; Note: This is similar to `renameat` in POSIX.
  (@interface func (export "rename")
    (param $fd $fd)
    ;;; 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.
    (param $new_fd $fd)
    ;;; The destination path to which to rename the file or directory.
    (param $new_path string)
    (result $error $errno)
  )

  ;;; Create a symbolic link.
  ;;; Note: This is similar to `symlinkat` in POSIX.
  (@interface func (export "symlink")
    ;;; The contents of the symbolic link.
    (param $old_path string)
    (param $fd $fd)
    ;;; The destination path at which to create the symbolic link.
    (param $new_path string)
    (result $error $errno)
  )

  ;;; Unlink a file.
  ;;; Return `errno::isdir` if the path refers to a directory.
  ;;; Note: This is similar to `unlinkat(fd, path, 0)` in POSIX.
  (@interface func (export "unlink_file")
    (param $fd $fd)
    ;;; The path to a file to unlink.
    (param $path string)
    (result $error $errno)
  )
)