LLAPI\_POOL\_IS\_PINNED\_FILE(3) Lustre Library Functions LLAPI\_POOL\_IS\_PINNED\_FILE(3)

# [NAME](#NAME)

llapi\_pool\_is\_pinned\_fd, llapi\_pool\_is\_pinned\_file, llapi\_pool\_is\_pinned\_fid - test whether a Lustre file is pinned to an OST pool

# [SYNOPSIS](#SYNOPSIS)

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

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

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

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

# [DESCRIPTION](#DESCRIPTION)

The **llapi\_pool\_is\_pinned\_\*(3)** functions test whether a Lustre file currently has a **pool** entry for *pool\_name* in its **lustre.pin** extended attribute.

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\_is\_pinned\_fd()**, **llapi\_pool\_is\_pinned\_file()** and **llapi\_pool\_is\_pinned\_fid()** functions return **1** only if a matching **pool** entry for *pool\_name* is present in the **lustre.pin** attribute. They return **0** when no such entry exists, including when the **lustre.pin** attribute is missing entirely. On error, such as an invalid *pool\_name* argument, failures resolving a FID, or I/O or parse errors while reading the attribute, these functions return a negative error code (*-errno*), for example **-EINVAL** or **-ENOENT**.

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\_is\_pinned\_\*()** functions return **1** if a matching pool pin entry is present, **0** if not, and a negative error code (*-errno*) on failure.

# [ERRORS](#ERRORS)

[**ENAMETOOLONG**](#ENAMETOOLONG)

The *pool\_name* exceeds the maximum number of characters.

[**ENXIO**](#ENXIO)

The *pool\_name* was not specified.

[**EINVAL**](#EINVAL)

An invalid argument was specified.

# [EXAMPLES](#EXAMPLES)

```
#include <lustre/lustreapi.h>
int pinned;
pinned = llapi_pool_is_pinned_file(path, pool_name);
if (pinned < 0) {
	/* error: report and abort */
	fprintf(stderr, "llapi_pool_is_pinned_file failed: %s0,
		strerror(-pinned));
	exit(EXIT_FAILURE);
}
if (pinned) {
	/* file is pinned to this pool */
} else {
	/* file is not pinned to this pool */
}
```

# [AVAILABILITY](#AVAILABILITY)

The **llapi\_pool\_is\_pinned\_fd()**, **llapi\_pool\_is\_pinned\_file()**, and **llapi\_pool\_is\_pinned\_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\_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), [**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_is_pinned_file(3) from lustre 2.17.59-r1 (Chainguard OS)
Source: https://github.com/lustre/lustre-release