LLAPI\_POOL\_UNPIN\_FILE(3) Lustre Library Functions LLAPI\_POOL\_UNPIN\_FILE(3)

# [NAME](#NAME)

llapi\_pool\_unpin\_fd, llapi\_pool\_unpin\_file, llapi\_pool\_unpin\_fid - remove pool pinning from a Lustre file

# [SYNOPSIS](#SYNOPSIS)

```
#include <lustre/lustreapi.h>
```

```
int llapi_pool_unpin_fd(int fd, const char *pool_name);
```

```
int llapi_pool_unpin_file(const char *path, const char *pool_name);
```

```
int llapi_pool_unpin_fid(const char *lustre_dir, const struct lu_fid *fid,
                         const char *pool_name);
```

# [DESCRIPTION](#DESCRIPTION)

The **llapi\_pool\_unpin\_\*(3)** functions manipulate the Lustre **lustre.pin** extended attribute of a file in order to remove any pin for a particular OST pool.

Pool pins are stored as YAML entries of the form

```
pool: pool_name
```

inside the **lustre.pin** attribute, which may also contain other entries such as **hsm** pins used by the PCC subsystem. Multiple pool pins and PCC pins can coexist in the same attribute.

The **llapi\_pool\_unpin\_fd()**, **llapi\_pool\_unpin\_file()** and **llapi\_pool\_unpin\_fid()** functions remove the **pool** entry for *pool\_name* from the **lustre.pin** attribute of the referenced file. If no matching entry is found, or if the **lustre.pin** attribute is missing, the call fails with **ENOENT** and the file is not modified. When the last entry is removed from **lustre.pin ,** the attribute itself is deleted.

The *pool\_name* parameter may optionally be qualified with a filesystem name using the "fsname.pool" notation commonly used by Lustre tools. In this case the "fsname." prefix is silently discarded before the pool name is stored or compared, and only the unqualified pool name is recorded in the **lustre.pin** attribute.

# [RETURN VALUES](#RETURN_VALUES)

The **llapi\_pool\_unpin\_\*()** functions return 0 on success. On failure they return a negative errno value and set **errno** to the corresponding error code.

# [ERRORS](#ERRORS)

Errors from [**llapi\_pool\_name\_validate**(3)](/man/enterprise-packages/lustre/llapi_pool_name_validate.3) will be returned on malformed pool names.

[**EINVAL**](#EINVAL)

An invalid argument was specified.

[**ENOENT**](#ENOENT)

No pool entry for the specified *pool\_name* was found in the **lustre.pin** attribute when calling one of the **llapi\_pool\_unpin\_\*()** functions, or the attribute itself was missing.

# [EXAMPLES](#EXAMPLES)

```
#include <lustre/lustreapi.h>
if (llapi_pool_unpin_file(path, pool_name) < 0) {
	if (errno == ENOENT) {
		/* file was not pinned to this pool */
	} else {
		perror("llapi_pool_unpin_file");
	}
}
```

# [AVAILABILITY](#AVAILABILITY)

The **llapi\_pool\_unpin\_fd()**, **llapi\_pool\_unpin\_file()**, and **llapi\_pool\_unpin\_fid()** functions are part of the [**lustre**(7)](/man/enterprise-packages/lustre/lustre.7) user application interface library since release 2.18.0.

# [SEE ALSO](#SEE_ALSO)

[**llapi\_pool\_is\_pinned\_file**(3)](/man/enterprise-packages/lustre/llapi_pool_is_pinned_file.3), [**llapi\_pool\_name\_validate**(3)](/man/enterprise-packages/lustre/llapi_pool_name_validate.3), [**llapi\_pool\_pin\_file**(3)](/man/enterprise-packages/lustre/llapi_pool_pin_file.3), [**lustre**(7)](/man/enterprise-packages/lustre/lustre.7), [**lustreapi**(7)](/man/enterprise-packages/lustre/lustreapi.7)

2026-08-23 Lustre User API

---

Document: llapi_pool_unpin_file(3) from lustre 2.17.59-r2 (Chainguard OS)
Source: https://github.com/lustre/lustre-release