.\" cvaffinity.1: auto-generated, DO NOT EDIT
.\"
.\" Copyright 1999-2023. Quantum Corporation. All Rights Reserved.
.\" StorNext is either a trademark or registered trademark of
.\" Quantum Corporation in the US and/or other countries.
.\"
.\" Code start macro
.de Cs
.sp
.ft C
.in +0.3i
.nf
..
.\" Code end macro
.de Ce
.fi
.in -0.3i
.ft R
..
.TH CVAFFINITY 1 "January 2023" "Xsan File System"
.SH NAME
cvaffinity \- set, get, or delete the affinity of a file or directory
.SH SYNOPSIS
.na
.nh
.HP
.B cvaffinity [-r]
.BI -s\ key
.I filename [filename...]
.HP
.B cvaffinity
.B [-r] -l
.I filename [filename...]
.HP
.B cvaffinity
.B [-r] -d
.I filename [filename...]
.ad
.hy
.SH DESCRIPTION
.PP
\fBcvaffinity\fR can be used to set an affinity for a specific
storage pool on a file or directory, or list the current affinity.
An affinity is created in a storage pool through the volume
configuration,
see
.BR snfs_config (5).
It is a name, up to eight (8) characters,
describing a special media type. Use
.BR cvadmin (8)
to see what
affinity sets are assigned to the configured storage pools.
.PP
If the affinity does not exist on any of the storage pools,
a set will fail.
When allocating space for a file with an affinity,
if the affinity does not exist for any of the storage pools,
or if the storage pools with the affinity cannot be used
to satisfy an allocation request,
then the allocation will occur on the non-exclusive storage pools.
If there is no non-exclusive storage pools, an \fBENOSPC\fR is returned.
See also \fBAffinityPreference\fP in
.BR snfs_config (5).
.PP
If a file does not have an affinity, it cannot have space allocated to it on storage pools that have any affinities and are configured to be exclusive.
.PP
A common way to use the affinity capability, is to create a directory with
.BR cvmkdir (1)
and have all files and directories below that directory inherit the affinity.
Also, files can be created and have space pre-allocated with an affinity using
.BR cvmkfile (1).
.PP
For automatic affinity mapping for certain files, see
\fBautoAffinity\fP and \fBautoAffinities\fP in
.BR snfs_config (5)
and
.BR snfs.cfgx (5).
.SH OPTIONS
.IP "\fB-s\fP \fIkey\fP"
Set the given \fIkey\fR to be the Affinity Key of the given file or directory.
This key must be configured as an Affinity in the storage pool
section of the file system configuration. Use
.BR cvadmin (8)
to see the affinities in this file system.
For files with an Affinity, new blocks allocated
to that file are placed on a storage pool with the
specified Affinity.  For directories with an Affinity
new files created in that directory inherit the Affinity
from the directory.
.PP
.IP \fB-l\fR
This option says to just list the affinity for the specified
file and exit.
.PP
.IP \fB-d\fR
This option says to delete the affinity from the specified
file or directory, if one exists.
.IP \fB-r\fR
This option says to run recursively for directories.
.PP
.IP \fIfilename\fR
Specifies the file or directory operated on. Multiple \fIfilename\fR arguments
are permitted.
.SH EXAMPLES
List the affinity on the file \fI/usr/clips/foo\fP.
.Cs
rock # cvaffinity -l /usr/clips/foo
.Ce
.PP
Set this file or directory to use the storage pool that has the \fBjmfn8\fR affinity type.
.Cs
rock # cvaffinity -s jmfn8 /usr/clips/filename
.Ce
.PP
Remove the affinity from the \fI/usr/clips/mydir\fP, if one is currently
assigned.
.Cs
rock # cvaffinity -d /usr/clips/mydir
.Ce
.SH "NOTES"
With regard to symbolic links, the recursive behavior of \fBcvaffinity\fR
is similar to the Linux "find" command when run with defaults. That is,
when symbolic links are encountered, the specified operation is performed
on the object pointed to by the link even when the object resides outside
of the hierarchy covered by the top-level argument. However,
\fBcvaffinity\fR will not recurse into directories pointed to by a
symbolic link.
.PP
File system objects that are neither regular files nor directories such as
device files and unix domain sockets cannot have affinities. If such
objects are specified on the command line, an error will be generated.
However, if such objects are encountered as part of a recursive operation,
they are simply ignored without an error being generated.
.PP
The return value will be non-zero if any error is encountered for any
argument. This includes any errors encountered while recursively
traversing a directory.
.SH "SEE ALSO"
.BR snfs_config (5),
.BR cvadmin (8)