---
title: "path_unlink_file()"
description: "Unlink a file, deleting it if the number of hardlinks is 1."
url: "https://wasix.org/docs/api-reference/wasi/path_unlink_file/"
markdown: "https://wasix.org/docs/api-reference/wasi/path_unlink_file.md"
---

# `path_unlink_file()`

Unlink a file, deleting it if the number of hardlinks is 1.

## Description

The `path_unlink_file()` function unlinks a file at the specified path. If the file has only one hardlink (i.e., its link count is 1), it will be deleted from the file system. It requires the `PATH_UNLINK_FILE` right on the base file descriptor.

On POSIX systems, a similar functionality is provided by the `unlink()` function. It removes the specified file from the file system. If the file has no other hardlinks, it is completely deleted. The `unlink()` function is part of the POSIX standard and is widely supported across different platforms.

## Syntax

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

## Parameters

- `ctx`: A mutable reference to the function environment.
- `fd`: The file descriptor representing the base directory from which the path is understood.
- `path`: A wasm pointer to a null-terminated string containing the path of the file to be unlinked.
- `path_len`: The length of the `path` string.

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

- `%fd`: The file descriptor representing the base directory.
- `path`: The path string.

## Note

The `path_unlink_file()` function unlinks a file at the specified path, deleting it if the number of hardlinks is 1. It checks the necessary rights on the base file descriptor. On POSIX systems, a similar functionality is provided by the `unlink()` function.

---

[Documentation index](https://wasix.org/llms.txt) · [HTML version](https://wasix.org/docs/api-reference/wasi/path_unlink_file/)