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

# [NAME](#NAME)

llapi\_pool\_pin\_fd, llapi\_pool\_pin\_file, llapi\_pool\_pin\_fid - pin a Lustre file to an OST pool

# [SYNOPSIS](#SYNOPSIS)

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

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

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

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

```

```

# [DESCRIPTION](#DESCRIPTION)

The **llapi\_pool\_pin\_\*(3)** functions manipulate the Lustre **lustre.pin** extended attribute of a file in order to record whether the file is pinned to 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\_pin\_fd()**, **llapi\_pool\_pin\_file()** and **llapi\_pool\_pin\_fid()** functions add a **pool** entry for the specified *pool\_name* to the **lustre.pin** extended attribute of the referenced file if it is not already present, leaving the attribute unchanged when the entry already exists.

The **llapi\_pool\_unpin\_fd()**, **llapi\_pool\_unpin\_file()** and **llapi\_pool\_unpin\_fid()** functions are documented in [**llapi\_pool\_unpin\_file**(3)](/man/enterprise-packages/lustre/llapi_pool_unpin_file.3).

The **llapi\_pool\_is\_pinned\_fd()**, **llapi\_pool\_is\_pinned\_file()** and **llapi\_pool\_is\_pinned\_fid()** functions are documented in [**llapi\_pool\_is\_pinned\_file**(3)](/man/enterprise-packages/lustre/llapi_pool_is_pinned_file.3).

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\_pin\_\*()** 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.

# [EXAMPLES](#EXAMPLES)

```
#include <lustre/lustreapi.h>
if (llapi_pool_pin_file(path, pool_name) < 0) {
	perror("llapi_pool_pin_file");
	/* handle error based on errno */
}
```

# [AVAILABILITY](#AVAILABILITY)

The **llapi\_pool\_pin\_fd()**, **llapi\_pool\_pin\_file()**, **llapi\_pool\_pin\_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\_unpin\_file**(3)](/man/enterprise-packages/lustre/llapi_pool_unpin_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_pin_fid(3) from lustre 2.17.59-r2 (Chainguard OS)
Source: https://github.com/lustre/lustre-release