path_open()

Open a file located at the given path.

Description

The path_open() function opens a file or directory at the specified path relative to the given directory. It provides various options for how the file will be opened, including read and write access, creation flags, and file descriptor flags.

On POSIX systems, a similar functionality is provided by the open() function. It opens a file or directory with the specified flags and mode. The open() function is a widely used system call for file operations in POSIX-compliant operating systems.

Syntax

  ;;; Note: This is similar to `openat` in POSIX.
  (@interface func (export "path_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
    ;;; `path_open::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_inheriting $rights)
    (param $fdflags $fdflags)
    ;;; The file descriptor of the file that has been opened.
    (result $error (expected $fd (error $errno)))
  )

Parameters

• ctx: A mutable reference to the function environment.
• dirfd: The file descriptor representing the directory that the file is located in.
• dirflags: Flags specifying how the path will be resolved.
• path: A wasm pointer to a null-terminated string containing the path of the file or directory to open.
• path_len: The length of the path string.
• o_flags: Flags specifying how the file will be opened.
• fs_rights_base: The rights of the created file descriptor.
• fs_rights_inheriting: The rights of file descriptors derived from the created file descriptor.
• fs_flags: The flags of the file descriptor.
• fd: A wasm pointer to a WasiFd variable where the new file descriptor will be stored.

Return Value

The function returns an Errno value indicating the success or failure of the operation. If the operation is successful, it returns Errno::Success. Otherwise, it returns an appropriate Errno value.

Logging

This function has been instrumented with debug-level logging. It will log the following information:

• %dirfd: The file descriptor representing the source directory.
• path: The path of the file or directory to open.
• follow_symlinks: A boolean indicating whether to follow symbolic links.
• ret_fd: The new file descriptor.

Note

The path_open() function opens a file or directory located at the specified path. It provides options for controlling how the file will be opened, including read and write access, creation flags, and file descriptor flags. The function checks the necessary rights and permissions before opening the file.

On POSIX systems, a similar functionality is provided by the open() function.