.TH LLAPI_POOL_UNPIN_FILE 3 2026-08-23 "Lustre User API" "Lustre Library Functions"
.SH NAME
llapi_pool_unpin_fd, llapi_pool_unpin_file, llapi_pool_unpin_fid \- remove pool pinning from a Lustre file
.SH SYNOPSIS
.nf
.B #include <lustre/lustreapi.h>
.PP
.BI "int llapi_pool_unpin_fd(int " fd ", const char *" pool_name ");"
.PP
.BI "int llapi_pool_unpin_file(const char *" path ", const char *" pool_name ");"
.PP
.BI "int llapi_pool_unpin_fid(const char *" lustre_dir ", const struct lu_fid *" fid ","
.BI "                         const char *" pool_name ");"
.fi
.SH DESCRIPTION
The
.B llapi_pool_unpin_*(3)
functions manipulate the Lustre
.B lustre.pin
extended attribute of a file in order to remove any pin for a particular
OST pool.
.PP
Pool pins are stored as YAML entries of the form
.RS
.nf
pool: \fIpool_name\fP
.fi
.RE
inside the
.B lustre.pin
attribute, which may also contain other entries such as
.B hsm
pins used by the PCC subsystem.
Multiple pool pins and PCC pins can coexist in the same attribute.
.PP
The
.BR llapi_pool_unpin_fd() ,
.BR llapi_pool_unpin_file()
and
.BR llapi_pool_unpin_fid()
functions remove the
.B pool
entry for
.I pool_name
from the
.B lustre.pin
attribute of the referenced file.
If no matching entry is found,
or if the
.B lustre.pin
attribute is missing, the call fails with
.B ENOENT
and the file is not modified.
When the last entry is removed from
.B lustre.pin ,
the attribute itself is deleted.
.PP
The
.I 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
.B lustre.pin
attribute.
.SH RETURN VALUES
The
.B llapi_pool_unpin_*()
functions return 0 on success. On failure they return a negative errno value
and set
.B errno
to the corresponding error code.
.SH ERRORS
Errors from
.BR llapi_pool_name_validate (3)
will be returned on malformed pool names.
.TP 15
.B EINVAL
An invalid argument was specified.
.TP 15
.B ENOENT
No pool entry for the specified
.I pool_name
was found in the
.B lustre.pin
attribute when calling one of the
.B llapi_pool_unpin_*()
functions, or the attribute itself was missing.
.SH EXAMPLES
.EX
#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");
	}
}
.EE
.in
.PP
.SH AVAILABILITY
The
.BR llapi_pool_unpin_fd() ,
.BR llapi_pool_unpin_file() ,
and
.BR llapi_pool_unpin_fid()
functions are part of the
.BR lustre (7)
user application interface library since release 2.18.0.
.\" Added in commit v2_17_52-151-g86b0c90666
.SH SEE ALSO
.BR llapi_pool_is_pinned_file (3),
.BR llapi_pool_name_validate (3),
.BR llapi_pool_pin_file (3),
.BR lustre (7),
.BR lustreapi (7)