-.TH lustreapi 3 "2019 Jul 10" "Lustre User API"
+.TH LLAPI_GET_FSNAME_INSTANCE 3 2024-08-26 "Lustre User API" "Lustre Library Functions"
.SH NAME
-llapi_get_fsname_instance - get the client filesystem name and instance
-.br
-llapi_get_fsname - get the filesystem fsname from path
-.br
-llapi_get_instance - get the client filesystem instance from path
-.br
-llapi_getname - get the client filesystem identifier from path
+llapi_get_fsname_instance, llapi_get_fsname, llapi_get_instance, llapi_getname - get the client filesystem name and instance
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
.B #include <sys/stat.h>
.B #include <fcntl.h>
.B #include <lustre/lustreapi.h>
-.sp
+.PP
.BI "int llapi_getname(const char *" path ", char *" name ", size_t " namelen );
-.sp
+.PP
.BI "int llapi_get_fsname_instance(const char *" path ", char *" fsname ,
-.BI size_t " fsname_len" ", char *" instance ,
-.BI size_t " instance_len" );
-.sp
+.BI " size_t " fsname_len ", char *" instance ,
+.BI " size_t " instance_len );
+.PP
.BI "int llapi_get_fsname(const char *" path ", char *" fsname ,
-.BI size_t " fsname_len" );
-.sp
+.BI " size_t " fsname_len );
+.PP
.BI "int llapi_get_instance(const char *" path ", char *" instance ,
-.BI size_t " instance_len" );
+.BI " size_t " instance_len );
+.fi
.SH DESCRIPTION
.LP
.B llapi_get_fsname_instance()
error code on failure and sets errno appropriately.
.SH ERRORS
.TP 15
-.SM EINVAL
+.B EINVAL
Invalid filesystem information found.
.TP
-.SM ENAMETOOLONG
+.B ENAMETOOLONG
The
.IR fsname_len ,
.IR instance_len ,
or
.I namelen
buffer length was not large enough to hold the string.
+.SH AVAILABILITY
+.BR llapi_get_fsname_instance() ,
+.BR llapi_get_fsname() ,
+.BR llapi_get_instance() ,
+and
+.B llapi_getname()
+are part of the
+.BR lustre (7)
+user application interface library.
+.B llapi_get_fsname_instance
+and
+.B llapi_get_fsname
+were added in release 2.14.0.
+.\" Added in commit v2_13_51-19-g00d14521ca
+.B llapi_get_instance
+and
+.B llapi_getname
+were added in release 2.2.0.
+.\" Added in commit 2.1.52-55-g8d935e6d31
.SH SEE ALSO
.BR lfs-getname (1),
.BR lustreapi (7)
-.TH llapi_get_lum_file_fd 3 "2019 July 15" "Lustre User API"
+.TH LLAPI_GET_LUM_FILE_FD 3 2024-08-27 "Lustre User API" "Lustre Library Functions"
.SH NAME
-llapi_get_lum_file_fd, llapi_get_lum_dir_fd, llapi_get_lum_file,
-llapi_get_lum_dir \- get valid file attributes and LOV stripe information to
-the user.
-
+llapi_get_lum_file_fd, llapi_get_lum_dir_fd, llapi_get_lum_file, llapi_get_lum_dir \- get valid file attributes and LOV stripe information to the user.
.SH SYNOPSIS
.nf
.B #include <lustre/lustreapi.h>
.BI " size_t " lumsize ");"
.PP
.BI "int llapi_get_lum_dir_fd(int " dir_fd ", __u64 *" valid ",
-.BI " lstatx_t *" statx ", struct lov_user_md *" lum ",
-.BI " size_t " lumsize ");"
+.BI " lstatx_t *" statx ", struct lov_user_md *" lum ",
+.BI " size_t " lumsize ");"
.PP
.BI "int llapi_get_lum_file(const char *" path ", __u64 *" valid ",
.BI " lstatx_t *" statx ", struct lov_user_md *" lum ",
.BI " size_t " lumsize ");"
.fi
.SH DESCRIPTION
-.PP
The function
.BR llapi_get_lum_file_fd() ,
.BR llapi_get_lum_dir_fd() ,
is provided, it is a relative pathname that is interpreted relative to the
directory referred to by
.BR dir_fd .
-
+.P
The function
.BR llapi_get_lum_dir_fd() ,
.BR llapi_get_lum_file() ,
.BR dir_fd
or
.BR path .
-
+.P
The function
.BR llapi_get_lum_file_fd()
can be used for applications that process lots of files. It avoids opening,
with a single open for all files in that directory, and it also does not
pollute the client dcache with millions of dentries when traversing a large
filesystem.
-
+.P
The stripe information for the target file is returned to the user in the
.B struct lov_user_md
pointed to by
.BR valid
contains the flags to indicate which fields in the returned file attributes
have been validly filled in.
-
+.P
The valid flags are as follows:
-.TP
+.TP 20
OBD_MD_FLSIZE
The returned file size is known strictly correct.
.TP
return 0 on success or a negative errno value on failure.
.SH ERRORS
.TP 15
-.SM -ENOMEM
+.B -ENOMEM
Insufficient memory to complete operation.
.TP
-.SM -EFAULT
+.B -EFAULT
Memory region is not properly mapped.
.TP
-.SM -EINVAL
+.B -EINVAL
One or more invalid arguments are given.
.TP
-.SM -EOPNOTSUPP
+.B -EOPNOTSUPP
The operation is not supported.
.TP
-.SM -ENOTTY
+.B -ENOTTY
File does not reside on a Lustre filesystem.
.TP
-.SM -ENOENT
+.B -ENOENT
.I path
does not exist.
.TP
-.SM -EBADF
+.B -EBADF
.I dir_fd
is not a valid open file descriptor.
-.SH "SEE ALSO"
+.SH AVAILABILITY
+.BR llapi_get_lum_file_fd() ,
+.BR llapi_get_lum_file() ,
+.B llapi_get_lum_dir_fd()
+and
+.B llapi_get_lum_dir()
+are part of the
+.BR lustre (7)
+user application interface library since release 2.13.0
+.\" Added in commit v2_12_58-78-g11aa7f8704
+.SH SEE ALSO
.BR lustreapi (7)
-.TH llapi_group_lock 3 "2014 Oct 03" "Lustre User API"
+.TH LLAPI_GROUP_LOCK 3 2024-08-27 "Lustre User API" "Lustre Library Functions"
.SH NAME
llapi_group_lock, llapi_group_unlock, llapi_group_lock64, llapi_group_unlock64 \- get and put a Lustre group lock.
.SH SYNOPSIS
.PP
.BI "int llapi_group_lock(int "fd ", int "gid );
.BI "int llapi_group_lock64(int "fd ", __u64 "gid );
-
+.PP
.BI "int llapi_group_unlock(int "fd ", int "gid );
.BI "int llapi_group_unlock64(int "fd ", __u64 "gid );
.fi
with group identifier
.IR gid
(int or __u64 type) .
-
+.P
The functions
.BR llapi_group_unlock()
and
.I gid
(int or __u64 type) on the file descriptor
.IR fd .
-
-The group lock is a whole file lock that blocks concurrent I/O originating from descriptors that have not been locked. Multiple processes can acquire a lock by specifying the same group identifier.
-
+.P
+The group lock is a whole file lock that blocks concurrent I/O originating
+from descriptors that have not been locked.
+Multiple processes can acquire a lock by specifying the same group identifier.
.SH RETURN VALUES
-.LP
.B llapi_group_lock(\|),
.B llapi_group_lock64(\|),
.B llapi_group_unlock(\|)
return 0 on success or a negative errno value on failure.
.SH ERRORS
.TP 15
-.SM -EBADF
+.B -EBADF
.I fd
is not a valid file descriptor.
.TP
-.SM -ENOTTY
+.B -ENOTTY
.I fd
does not describe an object suitable for this request.
.TP
-.SM -EINVAL
+.B -EINVAL
.I fd
is already group locked with a different group identifier.
-.TP
-.SH "SEE ALSO"
+.SH AVAILABILITY
+.BR llapi_group_lock() ,
+.BR llapi_group_unlock() ,
+.B llapi_group_lock64()
+and
+.B llapi_group_unlock64()
+are part of the
+.BR lustre (7)
+user application interface library.
+.B llapi_group_lock
+and
+.B llapi_group_unlock
+were added in releease 2.7.0.
+.\" Added in commit v2_6_53_0-11-ge73cf72b82
+.B llapi_group_lock64
+and
+.B llapi_group_unlock64
+were added in release 2.15.0.
+.\" Added in commit v2_14_51-124-gccb64cde7f
+.SH SEE ALSO
.BR lustreapi (7)
-.TH llapi_heat_get 3 "2019 Feb 09" "Lustre User API"
+.TH LLAPI_HEAT_GET 3 2024-08-27 "Lustre User API" "Lustre Library Functions"
.SH NAME
llapi_heat_get, llapi_heat_set \- get and clear heat for a file
.SH SYNOPSIS
.B #include <lustre/lustreapi.h>
.PP
.BI "int llapi_heat_get(int " fd ", struct lu_heat *" heat ");"
-
+.PP
.BI "int llapi_heat_set(int " fd ", __u64 " flags ");"
.fi
.SH DESCRIPTION
-.PP
The function
.B llapi_heat_get()
returns file access frequency information on the file descriptor
.TP
LU_HEAT_FLAG_OFF
Turn off the file heat support for a given file.
-
.SH RETURN VALUES
-.LP
.B llapi_heat_get()
and
.B llapi_heat_set()
return 0 on success or a negative errno value on failure.
.SH ERRORS
.TP 15
-.SM -ENOMEM
+.B -ENOMEM
Insufficient memory to complete operation.
.TP
-.SM -EFAULT
+.B -EFAULT
Memory region is not properly mapped.
.TP
-.SM -EINVAL
+.B -EINVAL
One or more invalid arguments are given.
.TP
-.SM EOPNOTSUPP
+.B EOPNOTSUPP
File heat operation is not supported.
-.SH "SEE ALSO"
+.SH AVAILABILITY
+.B llapi_heat_get()
+and
+.B llapi_heat_set()
+are part of the
+.BR lustre (7)
+user application interface library since release 2.13.0
+.\" Added in commit v2_12_52-52-gae723cf816
+.SH SEE ALSO
.BR lustreapi (7)
-.
-.TH LLAPI_HSM_ACTION_BEGIN 3 "2014-09-24" "" "Lustre HSM User API"
+.TH LLAPI_HSM_ACTION_BEGIN 3 2024-08-27 "Lustre User API" "Lustre Library Functions"
.SH NAME
-llapi_hsm_action_begin \- Lustre API copytool management
-.
+llapi_hsm_action_begin, llapi_hsm_action_end, llapi_hsm_action_progress, llapi_hsm_action_get_dfid, llapi_hsm_action_get_fd \- Lustre API copytool management
.SH SYNOPSIS
-.sp
-\fB#include <lustre/lustreapi.h>\fP
-.sp
-\fBint llapi_hsm_action_begin(struct hsm_copyaction_private **\fPphcp\fB,
-const struct hsm_copytool_private *\fPct\fB, const struct
-hsm_action_item *\fPhai\fB, int\fP restore_mdt_index\fB, int\fP
-restore_open_flags\fB, bool\fP is_error\fB)\fP
-.sp
-\fBint llapi_hsm_action_end(struct hsm_copyaction_private **\fPphcp\fB,
-const struct hsm_extent *\fPhe\fB, int\fP hp_flags\fB, int\fP errval\fB)\fP
-.sp
-\fBint llapi_hsm_action_progress(struct hsm_copyaction_private *\fPhcp\fB,
-const struct hsm_extent *\fPhe\fB, __u64\fP total\fB, int\fP hp_flags\fB)\fP
-.sp
-\fBint llapi_hsm_action_get_dfid(const struct hsm_copyaction_private *\fPhcp\fB,
-lustre_fid *\fPfid\fB)\fP
-.sp
-\fBint llapi_hsm_action_get_fd(const struct hsm_copyaction_private *\fPhcp\fB)\fP
+.nf
+.B #include <lustre/lustreapi.h>
+.PP
+.BI "int llapi_hsm_action_begin(struct hsm_copyaction_private **" phcp ,
+.BI " const struct hsm_copytool_private *" ct ,
+.BI " const struct hsm_action_item *" hai ,
+.BI " int " restore_mdt_index ,
+.BI " int " restore_open_flags ", bool " is_error );
+.PP
+.BI "int llapi_hsm_action_end(struct hsm_copyaction_private **" phcp ,
+.BI " const struct hsm_extent *" he ", int " hp_flags ,
+.BI " int " errval );
+.PP
+.BI "int llapi_hsm_action_progress(struct hsm_copyaction_private *" hcp ,
+.BI " const struct hsm_extent *" he ,
+.BI " __u64 " total ", int " hp_flags );
+.PP
+.BI "int llapi_hsm_action_get_dfid(const struct hsm_copyaction_private *" hcp ,
+.BI " lustre_fid *" fid );
+.PP
+.BI "int llapi_hsm_action_get_fd(const struct hsm_copyaction_private *" hcp );
+.fi
.SH DESCRIPTION
-.sp
When a copytool is ready to process an HSM action received through
-\fBllapi_hsm_copytool_recv\fP(), it must first call
-\fBllapi_hsm_action_begin\fP() to initialize the internal action
-state, stored in \fIphcp\fP\&. \fIct\fP is the opaque copytools handle
-previously returned by \fBllapi_hsm_copytool_register\fP(). \fIhai\fP is
-the request. \fIrestore_mdt_index\fP and \fIrestore_open_flags\fP are only
-used for an \fBHSMA_RESTORE\fP type of request. \fIrestore_mdt_index\fP is
-the MDT index on which to create the restored file, or \-1 for
-default. If the copytool does not intend to process the request, it
-should set \fIis_error\fP to \fBtrue\fP, and then call
-\fBllapi_hsm_action_end\fP().
-.sp
+.BR llapi_hsm_copytool_recv() ,
+it must first call
+.B llapi_hsm_action_begin()
+to initialize the internal action state, stored in
+.IR phcp .
+.I ct
+is the opaque copytools handle
+previously returned by
+.BR llapi_hsm_copytool_register() .
+.I hai
+is the request.
+.I restore_mdt_index
+and
+.I restore_open_flags
+are only used for an
+.B HSMA_RESTORE
+type of request.
+.I restore_mdt_index
+is the MDT index on which to create the restored file, or \-1 for default.
+If the copytool does not intend to process the request, it should set
+.I is_error
+to
+.BR true ,
+and then call
+.BR llapi_hsm_action_end() .
+.P
While performing a copy (i.e. the HSM request is either
-\fBHSMA_ARCHIVE\fP or \fBHSMA_RESTORE\fP), the copytool can inform Lustre
-of the progress of the operation with \fBllapi_hsm_action_progress\fP(). \fIhe\fP is the interval (\fIoffset\fP, \fIlength\fP) of the data copied. Each
-interval must be unique; i.e. there must not be any overlap. \fIlength\fP
-is the total length that is expected to be transfered. \fIhp_flags\fP
+.B HSMA_ARCHIVE
+or
+.BR HSMA_RESTORE ),
+the copytool can inform Lustre of the progress of the operation with
+.BR llapi_hsm_action_progress() .
+.I he
+is the interval
+.RI ( offset ", " length )
+of the data copied.
+Each interval must be unique; i.e. there must not be any overlap.
+.I length
+is the total length that is expected to be transfered.
+.I hp_flags
should be 0. The progress can be checked on any Lustre client by
-calling \fBllapi_hsm_current_action\fP(), or by using \fBlfs
-hsm_action\fP\&.
-.sp
+calling
+.BR llapi_hsm_current_action() , or by using
+.BR lfs hsm_action .
+.P
Once the HSM request has been performed, the destination file must be
-closed, and \fBllapi_hsm_action_end\fP() must be called to free\-up the
+closed, and
+.B llapi_hsm_action_end()
+must be called to free\-up the
allocated resources and signal Lustre that the file is now available
-to consumers. \fIerrval\fP is set to 0 on success. On error, it must be an
-errno, and hp_flags can be set to \fBHP_FLAG_RETRY\fP if the request is
-retryable, 0 otherwise. \fIhe\fP is the interval (\fIoffset\fP, \fIlength\fP) of
-the data copied. It can be the \fIhai_extent\fP of the HSM request.
-.sp
+to consumers.
+.I errval
+is set to 0 on success. On error, it must be an errno,
+and hp_flags can be set to
+.B HP_FLAG_RETRY
+if the request is retryable, 0 otherwise.
+.I he
+is the interval
+.IR ( offset ", " length )
+of the data copied. It can be the
+.I hai_extent
+of the HSM request.
+.P
For a restore operation, a volatile file, invisible to ls, is
-created. \fBllapi_hsm_action_get_fd\fP() will return a file descriptor
-to it. It is the responsibility of the copytool to close the returned
-file descriptor when the data transfer is
-done. \fBllapi_hsm_action_get_dfid\fP() will return the FID of the volatile
-file, which can then be used with \fBllapi_open_by_fid\fP() to open
-the file in a different process, or on a different node.
-.sp
-\fBllapi_hsm_action_get_fd\fP() and \fBllapi_hsm_action_get_dfid\fP()
+created.
+.B llapi_hsm_action_get_fd()
+will return a file descriptor to it.
+It is the responsibility of the copytool to close the returned
+file descriptor when the data transfer is done.
+.B llapi_hsm_action_get_dfid()
+will return the FID of the volatile file, which can then be used with
+.B llapi_open_by_fid()
+to open the file in a different process, or on a different node.
+.P
+.B llapi_hsm_action_get_fd()
+and
+.B llapi_hsm_action_get_dfid()
can be called for an archive operation too. The returned file
descriptor and the FID are from the file to be archived.
.SH RETURN VALUE
-.sp
-\fBllapi_hsm_action_get_fd\fP() returns a file descriptor on
-success. The other functions return 0 on success. All functions return
-a negative errno on failure.
+.B llapi_hsm_action_get_fd()
+returns a file descriptor on success. The other functions return 0 on success.
+All functions return a negative errno on failure.
.SH ERRORS
-.sp
The negative errno can be, but is not limited to:
+.TP 15
+.B -EINVAL
+An invalid value was passed, the copytool is not registered, ...
.TP
-.B \fB\-EINVAL\fP An invalid value was passed, the copytool is not
-registered, ...
-.TP
-.B \fB\-ENOMEM\fP Not enough memory to allocate a resource.
-.SH SEE ALSO
-.sp
-\fBllapi_hsm_copytool_register\fP(3), \fBllapi_hsm_copytool_recv\fP(3),
-\fBlustreapi\fP(7), \fBlfs\fP(1)
-.sp
-See \fIlhsmtool_posix.c\fP in the Lustre sources for a use case of this
-API.
-.SH AUTHOR
+.B -ENOMEM
+Not enough memory to allocate a resource.
+.SH AUTHORS
Frank Zago
-.
+.SH AVAILABILITY
+.BR llapi_hsm_action_begin(),
+.BR llapi_hsm_action_end(),
+.BR llapi_hsm_action_progress(),
+.B llapi_hsm_action_get_dfid()
+and
+.B llapi_hsm_action_get_fd()
+are part of the
+.BR lustre (7)
+user application interface library since release 2.4.0
+.\" Added in commit 2.3.53-7-gf715e4e298
+.SH SEE ALSO
+.BR lfs (1),
+.BR llapi_hsm_copytool_recv (3),
+.BR llapi_hsm_copytool_register (3),
+.BR lustreapi (7)
+.P
+See
+.I lhsmtool_posix.c
+in the Lustre sources for a use case of this API.
-.
-.TH LLAPI_HSM_COPYTOOL_REGISTER 3 "2014-09-24" "" "Lustre HSM User API"
+.TH LLAPI_HSM_COPYTOOL_REGISTER 3 2024-08-27 "Lustre User API" "Lustre Library Functions"
.SH NAME
-llapi_hsm_copytool_register \- Lustre API copytool management
-.
-.nr rst2man-indent-level 0
-.
-.de1 rstReportMargin
-\\$1 \\n[an-margin]
-level \\n[rst2man-indent-level]
-level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
--
-\\n[rst2man-indent0]
-\\n[rst2man-indent1]
-\\n[rst2man-indent2]
-..
-.de1 INDENT
-.\" .rstReportMargin pre:
-. RS \\$1
-. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
-. nr rst2man-indent-level +1
-.\" .rstReportMargin post:
-..
-.de UNINDENT
-. RE
-.\" indent \\n[an-margin]
-.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
-.nr rst2man-indent-level -1
-.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
-.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
-..
+llapi_hsm_copytool_register, llapi_hsm_copytool_unregister, llapi_hsm_copytool_get_fd, llapi_hsm_copytool_recv, hai_first, hai_next \- Lustre API copytool management
.SH SYNOPSIS
-.sp
-\fB#include <lustre/lustreapi.h>\fP
-.sp
-\fBint llapi_hsm_copytool_register(struct hsm_copytool_private **\fPpriv\fB,
-const char *\fPmnt\fB, int\fP archive_count\fB, int *\fParchives\fB,
-int\fP rfd_flags\fB)\fP
-.sp
-\fBint llapi_hsm_copytool_unregister(struct hsm_copytool_private **\fPpriv
-\fB)\fP
-.sp
-\fBint llapi_hsm_copytool_get_fd(struct hsm_copytool_private *\fPct\fB)\fP
-.sp
-\fBint llapi_hsm_copytool_recv(struct hsm_copytool_private *\fPpriv\fB,
-**struct hsm_action_list **\fPhal\fB, int *\fPmsgsize\fB)\fP
-.sp
-\fBstruct hsm_action_item *hai_first(struct hsm_action_list *\fPhal\fB)\fP
-.sp
-\fBstruct hsm_action_item *hai_next(struct hsm_action_item *\fPhai\fB)\fP
+.nf
+.B #include <lustre/lustreapi.h>
+.PP
+.BI "int llapi_hsm_copytool_register(struct hsm_copytool_private **" priv ,
+.BI " const char *" mnt ", int " archive_count ,
+.BI " int *" archives ", int " rfd_flags );
+.PP
+.BI "int llapi_hsm_copytool_unregister(struct hsm_copytool_private **" priv );
+.PP
+.BI "int llapi_hsm_copytool_get_fd(struct hsm_copytool_private *" ct );
+.PP
+.BI "int llapi_hsm_copytool_recv(struct hsm_copytool_private *" priv ,
+.BI " struct hsm_action_list **" hal ,
+.BI " int *" msgsize );
+.PP
+.BI "struct hsm_action_item *hai_first(struct hsm_action_list *" hal );
+.PP
+.BI "struct hsm_action_item *hai_next(struct hsm_action_item *" hai );
+.fi
.SH DESCRIPTION
-.sp
-To receive HSM requests from a Lustre filesystem, a copytool
-application must register with Lustre by calling
-\fBllapi_hsm_copytool_register\fP(). The mountpoint of the Lustre
-filesystem to monitor is indicated by \fImnt\fP\&. \fIarchives\fP is an array
-with up to 32 elements indicating which archive IDs to register
-for. Each element is a number from 1 to 32. \fIarchive_count\fP is the
-number of valid elements in the \fIarchive\fP array. If an element in
-\fIarchives\fP is 0, or if \fIarchive_count\fP is 0, then all archives will be
-monitored. \fIrfd_flags\fP determines whether \fBllapi_hsm_copytool_recv\fP
+To receive HSM requests from a Lustre filesystem,
+a copytool application must register with Lustre by calling
+.BR llapi_hsm_copytool_register() .
+The mountpoint of the Lustre filesystem to monitor is indicated by
+.IR mnt .
+.I archives
+is an array with up to 32 elements indicating which archive IDs to register for.
+Each element is a number from 1 to 32.
+.I archive_count
+is the number of valid elements in the
+.I archive
+array. If an element in
+.I archives
+is 0, or if
+.I archive_count
+is 0, then all archives will be monitored.
+.I rfd_flags
+determines whether
+.B llapi_hsm_copytool_recv
will be blocking, with 0, or non\-blocking, with O_NONBLOCK.
-.sp
-\fBllapi_hsm_copytool_register\fP returns \fIpriv\fP, an opaque
-pointer that must be used with the other functions.
-.sp
-\fBllapi_hsm_copytool_unregister\fP unregisters a copytool. \fIpriv\fP is
-the opaque handle returned by \fBllapi_hsm_copytool_register\fP\&.
-.sp
-\fBllapi_hsm_copytool_get_fd\fP returns the file descriptor used by the
-library to communicate with the kernel. This descriptor is only
-intended to be used with \fBselect(2)\fP or \fBpoll(2)\fP\&. \fIrfd_flags\fP
+.PP
+.B llapi_hsm_copytool_register
+returns
+.IR priv ,
+an opaque pointer that must be used with the other functions.
+.P
+.B llapi_hsm_copytool_unregister
+unregisters a copytool.
+.I priv
+is the opaque handle returned by
+.BR llapi_hsm_copytool_register .
+.P
+.B llapi_hsm_copytool_get_fd
+returns the file descriptor used by the library to communicate with the kernel.
+This descriptor is only intended to be used with
+.BR select (2)
+or
+.BR poll (2).
+.I rfd_flags
should have been set to O_NONBLOCK.
-.sp
+.P
To receive the requests, the application has to call
-\fBllapi_hsm_copytool_recv\fP\&. When it returns 0, a message is available
-in \fIhal\fP, and its size in bytes is returned in \fImsgsize\fP\&. \fIhal\fP points
-to a buffer allocated by the Lustre library. It contains one or more
+.BR llapi_hsm_copytool_recv .
+When it returns 0, a message is available in
+.IR hal ,
+and its size in bytes is returned in
+.IR msgsize .
+.I hal
+points to a buffer allocated by the Lustre library. It contains one or more
HSM requests. This buffer is valid until the next call to
-\fBllapi_hsm_copytool_recv\fP\&.
-.sp
-\fIhal\fP is composed of a header of type \fIstruct hsm_action_list\fP
-followed by one or several HSM requests of type \fIstruct
-hsm_action_item\fP:
-.INDENT 0.0
-.INDENT 3.5
-.sp
+.BR llapi_hsm_copytool_recv .
+.P
+.I hal
+is composed of a header of type
+.B struct hsm_action_list
+followed by one or several HSM requests of type
+.BR "struct hsm_action_item" :
+.PP
+.RS 3.5
.nf
-.ft C
struct hsm_action_list {
__u32 hal_version;
__u32 hal_count; /* number of hai\(aqs to follow */
__u32 padding1;
char hal_fsname[]; /* null\-terminated name of filesystem */
};
-
+\&
struct hsm_action_item {
__u32 hai_len; /* valid size of this struct */
__u32 hai_action; /* hsm_copytool_action, but use known size */
__u64 hai_gid; /* grouplock id */
char hai_data[]; /* variable length */
};
-.ft P
.fi
-.UNINDENT
-.UNINDENT
+.RE
.sp
-To iterate through the requests, use \fBhai_first\fP to get the first
-request, then \fBhai_next\fP\&.
+To iterate through the requests, use
+.B hai_first
+to get the first request, then
+.BR hai_next .
.SH RETURN VALUE
-.sp
-\fBllapi_hsm_copytool_register\fP and \fBllapi_hsm_copytool_unregister\fP
+.B llapi_hsm_copytool_register
+and
+.B llapi_hsm_copytool_unregister
return 0 on success. On error, a negative errno is returned.
-.INDENT 0.0
.TP
-.B \fBllapi_hsm_copytool_get_fd\fP returns the file descriptor associated
-with the register copytool. On error, a negative errno is returned.
-.UNINDENT
-.sp
-\fBllapi_hsm_copytool_recv\fP returns 0 when a message is available. If
-the copytool was set to non\-blocking operation, \-EAGAIN is
-immediately returned if no message is available. On error, a negative
-errno is returned.
+.B llapi_hsm_copytool_get_fd
+returns the file descriptor associated with the register copytool. On error, a negative errno is returned.
+.P
+.B llapi_hsm_copytool_recv
+returns 0 when a message is available.
+If the copytool was set to non\-blocking operation,
+\-EAGAIN is immediately returned if no message is available.
+On error, a negative errno is returned.
.SH ERRORS
-.INDENT 0.0
+.TP 15
+.B -EINVAL
+An invalid value was passed, the copytool is not registered, ...
.TP
-.B \fB\-EINVAL\fP An invalid value was passed, the copytool is not
-registered, ...
-.UNINDENT
-.sp
-\fB\-ESHUTDOWN\fP The transport endpoint shutdown.
-.sp
-\fB\-EPROTO\fP Lustre protocol error.
-.sp
-\fB\-EAGAIN\fP No HSM message is available, and the copytool was set
-to not block on receives.
-.SH SEE ALSO
-.sp
-\fBllapi_hsm_action_begin\fP(3), \fBllapi_hsm_action_end\fP(3),
-\fBllapi_hsm_action_progress\fP(3), \fBllapi_hsm_action_get_dfid\fP(3),
-\fBllapi_hsm_action_get_fd\fP(3), \fBlustreapi\fP(7)
-.sp
-See \fIlhsmtool_posix.c\fP in the Lustre sources for a use case of this
-API.
-.SH AUTHOR
+.B -ESHUTDOWN
+The transport endpoint shutdown.
+.TP
+.B -EPROTO
+Lustre protocol error.
+.TP
+.B -EAGAIN
+No HSM message is available, and the copytool was set to not block on receives.
+.SH AUTHORS
Frank Zago
-.
+.SH AVAILABILITY
+.BR llapi_hsm_copytool_register() ,
+.BR llapi_hsm_copytool_unregister() ,
+.B llapi_hsm_copytool_get_fd()
+and
+.B llapi_hsm_copytool_recv()
+are part of the
+.BR lustre (7)
+user application interface library since release 2.4.0.
+.\" Added in commit 2.3.53-7-gf715e4e298
+.B hai_first()
+and
+.B hai_next()
+are part of the
+.BR lustre (7)
+user application interface library.
+.B hai_first
+was added in release 2.5.0.
+.\" Added in commit v2_4_90_0-15-g4b02a71242
+.B hai_next was added in release 2.0.0.
+.\" Added in commit v1_9_230~28
+.SH SEE ALSO
+.BR llapi_hsm_action_begin (3),
+.BR llapi_hsm_action_end (3),
+.BR llapi_hsm_action_get_dfid (3),
+.BR llapi_hsm_action_get_fd (3),
+.BR llapi_hsm_action_progress (3),
+.BR lustreapi (7)
+.P
+See
+.I lhsmtool_posix.c
+in the Lustre sources for a use case of this API.
-.TH lustreapi 3 "2014 Sep 22" Lustre "Lustre Application Interface Library"
+.TH LLAPI_HSM_STATE_GET 3 2024-08-27 "Lustre User API" "Lustre Library Functions"
.SH NAME
-llapi_hsm_state_get, llapi_hsm_state_get_fd \- get HSM state
-information for a file on a Lustre filesystem
+llapi_hsm_state_get, llapi_hsm_state_get_fd \- get HSM state information for a file on a Lustre filesystem
.SH SYNOPSIS
.nf
.B #include <lustre/lustreapi.h>
-.sp
+.PP
.BI "int llapi_hsm_state_get(const char *" path ", struct hsm_user_state *" hus ");"
-.sp
+.PP
.BI "int llapi_hsm_state_get_fd(int " fd ", struct hsm_user_state *" hus ");"
-.sp
.fi
.SH DESCRIPTION
-.LP
These functions return the HSM state flags and HSM archive ID for the
file referred to by
-.IR path
+.I path
or
.IR fd .
Information is returned in the
.I hus
argument which should already be allocated.
+.P
.nf
-.LP
struct hsm_user_state {
__u32 hus_states;
__u32 hus_archive_id;
.TP
.I hus_states
Flag mask for different HSM states and policy hints.
-.LP
-
+.PP
The value of
.I hus_states
is formed by bitwise or'ing the following possible states:
-
.TP 7
.B HS_EXISTS
The file has been assigned to an archive and provided to the backend
The file content in the archive is not available, and file can not be
restored. If this file is also HS_RELEASED, then attempts to access
the file will fail. This flag can be set by an administrator.
-
.SH RETURN VALUES
-.LP
-.B llapi_hsm_state_get(\|)
+.B llapi_hsm_state_get()
and
-.B llapi_hsm_state_get_fd(\|)
+.B llapi_hsm_state_get_fd()
return:
-.TP 7
+.TP
.B 0
on success
.TP
.B -errno
on failure
.SH ERRORS
-.TP 7
-.SM ENOMEM
+.TP 15
+.B -ENOMEM
failed to allocate memory.
.TP
-.SM ENAMETOOLONG
+.B -ENAMETOOLONG
.I path
was too long.
.TP
-.SM ENOENT
+.B -ENOENT
.I path
does not point to a file or a directory.
.TP
-.SM ENOTTY
+.B -ENOTTY
.I path
does not point to a Lustre filesystem.
-.SH EXAMPLE
+.SH EXAMPLES
.nf
#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
-
+\&
#include <lustre/lustreapi.h>
-
+\&
int main(int argc, char **argv)
{
struct hsm_user_state hus;
int rc;
-
+\&
if (argc < 2) {
fprintf(stderr, "usage: prog FILEPATH\\n");
exit(1);
}
-
+\&
rc = llapi_hsm_state_get(argv[1], &hus);
if (rc) {
fprintf(stderr, "can't get hsm state for %s: %s\\n",
argv[1], strerror(-rc));
exit(rc);
}
-
+\&
if (hus.hus_states & HS_RELEASED)
printf(" released");
if (hus.hus_states & HS_EXISTS)
printf(" exists");
if (hus.hus_states & HS_ARCHIVED)
printf(" archived");
-
+\&
/* Display settable flags */
if (hus.hus_states & HS_NORELEASE)
printf(" never_release");
printf(" dirty");
if (hus.hus_states & HS_LOST)
printf(" lost_from_hsm");
-
+\&
if (hus.hus_archive_id != 0)
printf(", archive_id:%d", hus.hus_archive_id);
-
+\&
printf("\\n");
-
+\&
exit(0);
}
.fi
-.SH "SEE ALSO"
-.BR lustre (7),
-.BR lustreapi (7),
+.SH AVAILABILITY
+.B llapi_hsm_state_get()
+and
+.B llapi_hsm_state_get_fd()
+are part of the
+.BR lustre (7)
+user application interface library since release 2.4.0
+.\" Added in commit 2.3.53-7-gf715e4e298
+.SH SEE ALSO
+.BR lfs-hsm (1),
.BR llapi_hsm_state_set (3),
.BR llapi_hsm_state_set_fd (3),
-.BR lfs-hsm (1)
+.BR lustre (7),
+.BR lustreapi (7)
-.TH lustreapi 3 "2012 Dec 21" Lustre "Lustre Application Interface Library"
+.TH LLAPI_HSM_STATE_SET 3 2024-08-27 "Lustre User API" "Lustre Library Functions"
.SH NAME
-llapi_hsm_state_set llapi_hsm_state_set_fd \- set HSM flags for a file on Lustre filesystem
+llapi_hsm_state_set, llapi_hsm_state_set_fd \- set HSM flags for a file on Lustre filesystem
.SH SYNOPSIS
.nf
.B #include <lustre/lustreapi.h>
-.sp
+.PP
.BI "int llapi_hsm_state_set(const char *" path ", __u64 " setmask ",
.BI " __u64 " clearmask ", __u32 " archive_id ");"
-.sp
+.PP
.BI "int llapi_hsm_state_set_fd(int " fd ", __u64 " setmask ",
.BI " __u64 " clearmask ", __u32 " archive_id ");"
-.sp
.fi
.SH DESCRIPTION
-.LP
-.B llapi_hsm_state_set(\|)
-.B llapi_hsm_state_set_fd(\|)
+.B llapi_hsm_state_set()
+.B llapi_hsm_state_set_fd()
sets, clears HSM flags and modifies archive ID for file pointed by
-.IR path
+.I path
or
.IR fd .
-
.TP 20
.I setmask
Mask of flags to be added.
-.TP 20
+.TP
.I clearmask
Mask of flags to be removed.
-.TP 20
+.TP
.I archive_id
Archive ID (greater than 0) used for this file. Use 0 if you do not want to
change it.
-.LP
+.PP
See
.BR llapi_hsm_state_get (3)
for available flags.
-.LP
.SH RETURN VALUES
-.LP
-.B llapi_hsm_state_set(\|)
-.B llapi_hsm_state_set_fd(\|)
+.B llapi_hsm_state_set()
+and
+.B llapi_hsm_state_set_fd()
return:
-.TP
+.TP 7
0
on success
.TP
is set appropriately.
.SH ERRORS
.TP 15
-.SM ENOMEM
+.B -ENOMEM
failed to allocate memory.
-.TP 15
-.SM ENAMETOOLONG
+.TP
+.B -ENAMETOOLONG
.I path
was too long.
-.TP 15
-.SM ENOENT
+.TP
+.B -ENOENT
.I path
does not point to a file or a directory.
-.TP 15
-.SM ENOTTY
+.TP
+.B -ENOTTY
.I path
does not point to a Lustre filesystem.
-.TP 15
-.SM EINVAL
+.TP
+.B -EINVAL
Provided masks resulted in an incompatible set of flags.
-.SH EXAMPLE
-
+.SH EXAMPLES
.nf
#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
-
+\&
#include <lustre/lustreapi.h>
-
+\&
int main(int argc, char **argv)
{
int rc;
-
+\&
if (argc < 2) {
fprintf(stderr, "usage: prog FILEPATH\\n");
exit(1);
}
-
+\&
rc = llapi_hsm_state_set(argv[1], HS_DIRTY|HS_NORELEASE, 0, 0);
if (rc != 0) {
fprintf(stderr, "Can't change hsm flags for %s: %s\\n",
argv[1], strerror(errno = -rc));
exit(rc);
}
-
+\&
exit(0);
}
.fi
-.SH "SEE ALSO"
+.SH AVAILABILITY
+.B llapi_hsm_state_set
+and
+.B llapi_hsm_state_set_fd
+are part of the
+.BR lustre (7)
+user application interface library since release 2.4.0
+.\" Added in commit 2.3.53-7-gf715e4e298
+.SH SEE ALSO
+.BR llapi_hsm_state_get (3),
+.BR llapi_hsm_state_get_fd (3),
.BR lustre (7),
-.BR lustreapi (7),
-.BR llapi_hsm_state_get (3)
-.BR llapi_hsm_state_get_fd (3)
+.BR lustreapi (7)
git://git.whamcloud.com / fs / lustre-release.git / commitdiff