llapi_layout_pattern_get.3 llapi_layout_pattern_set.3 \
llapi_layout_pool_name_get.3 llapi_layout_pool_name_set.3 \
llapi_layout_stripe_count_get.3 llapi_layout_stripe_count_set.3 \
- llapi_layout_stripe_size_get.3 llapi_layout_stripe_size_set.3 \
+ llapi_layout_stripe_size_get.3 llapi_layout_stripe_size_set.3 \
llapi_path2fid.3 llapi_group_lock.3 llapi_group_unlock.3 \
- ll_decode_filter_fid.8 llapi_path2parent.3 llapi_fd2parent.3
+ ll_decode_filter_fid.8 llapi_path2parent.3 llapi_fd2parent.3 \
+ llapi_hsm_copytool_unregister.3 llapi_hsm_copytool_get_fd.3 \
+ llapi_hsm_copytool_recv.3 llapi_hsm_action_end.3 \
+ llapi_hsm_action_progress.3 llapi_hsm_action_get_dfid.3 \
+ llapi_hsm_action_get_fd.3
SERVER_MANFILES = mkfs.lustre.8 tunefs.lustre.8
# Generated manpages with their sources in ReST. Generated files are
# not part of the dist target; they may or may not have been
# generated (see --disable-manpages option).
-RST_MANFILES = lustreapi.rst
-GEN_MANFILES = lustreapi.7
+RST_MANFILES = lustreapi.rst llapi_hsm_action_begin.rst \
+ llapi_hsm_copytool_register.rst
+GEN_MANFILES = lustreapi.7 llapi_hsm_action_begin.3 \
+ llapi_hsm_copytool_register.3
if UTILS
if MANPAGES
--- /dev/null
+======================
+llapi_hsm_action_begin
+======================
+
+------------------------------
+Lustre API copytool management
+------------------------------
+
+:Author: Frank Zago
+:Date: 2014-09-24
+:Manual section: 3
+:Manual group: Lustre HSM User API
+
+
+SYNOPSIS
+========
+
+**#include <lustre/lustreapi.h>**
+
+**int llapi_hsm_action_begin(struct hsm_copyaction_private \*\***\ phcp\ **,
+const struct hsm_copytool_private \***\ ct\ **, const struct
+hsm_action_item \***\ hai\ **, int** restore_mdt_index\ **, int**
+restore_open_flags\ **, bool** is_error\ **)**
+
+**int llapi_hsm_action_end(struct hsm_copyaction_private \*\***\ phcp\ **,
+const struct hsm_extent \***\ he\ **, int** hp_flags\ **, int** errval\ **)**
+
+**int llapi_hsm_action_progress(struct hsm_copyaction_private \***\ hcp\ **,
+const struct hsm_extent \***\ he\ **, __u64** total\ **, int** hp_flags\ **)**
+
+**int llapi_hsm_action_get_dfid(const struct hsm_copyaction_private \***\ hcp\ **,
+lustre_fid \***\ fid\ **)**
+
+**int llapi_hsm_action_get_fd(const struct hsm_copyaction_private \***\ hcp\ **)**
+
+
+DESCRIPTION
+===========
+
+When a copytool is ready to process an HSM action received through
+**llapi_hsm_copytool_recv**\ (), it must first call
+**llapi_hsm_action_begin**\ () to initialize the internal action
+state, stored in *phcp*. *ct* is the opaque copytools handle
+previously returned by **llapi_hsm_copytool_register**\ (). *hai* is
+the request. *restore_mdt_index* and *restore_open_flags* are only
+used for an **HSMA_RESTORE** type of request. *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 *is_error* to **true**, and then call
+**llapi_hsm_action_end**\ ().
+
+While performing a copy (i.e. the HSM request is either
+**HSMA_ARCHIVE** or **HSMA_RESTORE**), the copytool can inform Lustre
+of the progress of the operation with **llapi_hsm_action_progress**\
+(). *he* is the interval (*offset*, *length*) of the data copied. Each
+interval must be unique; i.e. there must not be any overlap. *length*
+is the total length that is expected to be transfered. *hp_flags*
+should be 0. The progress can be checked on any Lustre client by
+calling **llapi_hsm_current_action**\ (), or by using **lfs
+hsm_action**.
+
+Once the HSM request has been performed, the destination file must be
+closed, and **llapi_hsm_action_end**\ () must be called to free-up the
+allocated ressources and signal Lustre that the file is now available
+to consumers. *errval* is set to 0 on success. On error, it must be an
+errno, and hp_flags can be set to **HP_FLAG_RETRY** if the request is
+retryable, 0 otherwise. *he* is the interval (*offset*, *length*) of
+the data copied. It can be the *hai_extent* of the HSM request.
+
+For a restore operation, a volatile file, invisible to ls, is
+created. **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. **llapi_hsm_action_get_dfid**\ () will return the FID of the volatile
+file, which can then be used with **llapi_open_by_fid**\ () to open
+the file in a different process, or on a different node.
+
+**llapi_hsm_action_get_fd**\ () and **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.
+
+
+RETURN VALUE
+============
+
+**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.
+
+
+ERRORS
+======
+
+The negative errno can be, but is not limited to:
+
+**-EINVAL** An invalid value was passed, the copytool is not
+ registered, ...
+
+**-ENOMEM** Not enough memory to allocate a resource.
+
+
+SEE ALSO
+========
+
+**llapi_hsm_copytool_register**\ (3), **llapi_hsm_copytool_recv**\ (3),
+**lustreapi**\ (7), **lfs**\ (1)
+
+See *lhsmtool_posix.c* in the Lustre sources for a use case of this
+API.
--- /dev/null
+.so man3/llapi_hsm_action_begin.3
--- /dev/null
+.so man3/llapi_hsm_action_begin.3
--- /dev/null
+.so man3/llapi_hsm_action_begin.3
--- /dev/null
+.so man3/llapi_hsm_action_begin.3
--- /dev/null
+.so man3/llapi_hsm_copytool_register.3
--- /dev/null
+.so man3/llapi_hsm_copytool_register.3
--- /dev/null
+===========================
+llapi_hsm_copytool_register
+===========================
+
+------------------------------
+Lustre API copytool management
+------------------------------
+
+:Author: Frank Zago
+:Date: 2014-09-24
+:Manual section: 3
+:Manual group: Lustre HSM User API
+
+
+SYNOPSIS
+========
+
+**#include <lustre/lustreapi.h>**
+
+**int llapi_hsm_copytool_register(struct hsm_copytool_private \*\***\ priv\ **,
+const char \***\ mnt\ **, int** archive_count\ **, int \***\ archives\ **,
+int** rfd_flags\ **)**
+
+**int llapi_hsm_copytool_unregister(struct hsm_copytool_private \*\***\ priv
+**)**
+
+**int llapi_hsm_copytool_get_fd(struct hsm_copytool_private \***\ ct\ **)**
+
+**int llapi_hsm_copytool_recv(struct hsm_copytool_private \***\ priv\ **,
+**struct hsm_action_list \*\***\ hal\ **, int \***\ msgsize\ **)**
+
+**struct hsm_action_item \*hai_first(struct hsm_action_list \***\ hal\ **)**
+
+**struct hsm_action_item \*hai_next(struct hsm_action_item \***\ hai\ **)**
+
+
+DESCRIPTION
+===========
+
+To receive HSM requests from a Lustre filesystem, a copytool
+application must register with Lustre by calling
+**llapi_hsm_copytool_register**\ (). The mountpoint of the Lustre
+filesystem to monitor is indicated by *mnt*. *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. *archive_count* is the
+number of valid elements in the *archive* array. If an element in
+*archives* is 0, or if *archive_count* is 0, then all archives will be
+monitored. *rfd_flags* determines whether **llapi_hsm_copytool_recv**
+will be blocking, with 0, or non-blocking, with O_NONBLOCK.
+
+**llapi_hsm_copytool_register** returns *priv*, an opaque
+pointer that must be used with the other functions.
+
+**llapi_hsm_copytool_unregister** unregisters a copytool. *priv* is
+the opaque handle returned by **llapi_hsm_copytool_register**.
+
+**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 **select(2)** or **poll(2)**. *rfd_flags*
+should have been set to O_NONBLOCK.
+
+To receive the requests, the application has to call
+**llapi_hsm_copytool_recv**. When it returns 0, a message is available
+in *hal*, and its size in bytes is returned in *msgsize*. *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
+**llapi_hsm_copytool_recv**.
+
+*hal* is composed of a header of type *struct hsm_action_list*
+followed by one or several HSM requests of type *struct
+hsm_action_item*::
+
+ struct hsm_action_list {
+ __u32 hal_version;
+ __u32 hal_count; /* number of hai's to follow */
+ __u64 hal_compound_id; /* returned by coordinator */
+ __u64 hal_flags;
+ __u32 hal_archive_id; /* which archive backend */
+ __u32 padding1;
+ char hal_fsname[0]; /* 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 */
+ lustre_fid hai_fid; /* Lustre FID to operated on */
+ lustre_fid hai_dfid; /* fid used for data access */
+ struct hsm_extent hai_extent; /* byte range to operate on */
+ __u64 hai_cookie; /* action cookie from coordinator */
+ __u64 hai_gid; /* grouplock id */
+ char hai_data[0]; /* variable length */
+ };
+
+To iterate through the requests, use **hai_first** to get the first
+request, then **hai_next**.
+
+
+RETURN VALUE
+============
+
+**llapi_hsm_copytool_register** and **llapi_hsm_copytool_unregister**
+return 0 on success. On error, a negative errno is returned.
+
+**llapi_hsm_copytool_get_fd** returns the file descriptor associated
+ with the register copytool. On error, a negative errno is returned.
+
+**llapi_hsm_copytool_recv** returns 0 when a message is available. If
+the copytool was set to non-blocking operation, -EWOULDBLOCK is
+immediately returned if no message is available. On error, a negative
+errno is returned.
+
+
+ERRORS
+======
+
+**-EINVAL** An invalid value was passed, the copytool is not
+ registered, ...
+
+**-ESHUTDOWN** The transport endpoint shutdown.
+
+**-EPROTO** Lustre protocol error.
+
+**-EWOULDBLOCK** No HSM message is available, and the copytool was set
+to not block on receives.
+
+
+SEE ALSO
+========
+
+**llapi_hsm_action_begin**\ (3), **llapi_hsm_action_end**\ (3),
+**llapi_hsm_action_progress**\ (3), **llapi_hsm_action_get_dfid**\ (3),
+**llapi_hsm_action_get_fd**\ (3), **lustreapi**\ (7)
+
+See *lhsmtool_posix.c* in the Lustre sources for a use case of this
+API.
--- /dev/null
+.so man3/llapi_hsm_copytool_register.3
----------------------
:Author: Lustre contributors
-:Date: 2009-08-10
+:Date: 2014-09-21
:Manual section: 7
:Manual group: The Lustre API library
settings specific to the Lustre filesystem (allocation policies,
quotas, etc).
+The library provides the following functions:
+
+**HSM**
+
+ int llapi_hsm_copytool_register(struct hsm_copytool_private \*\*priv,
+ const char \*mnt, int archive_count, int \*archives,
+ int rfd_flags)
+
+ int llapi_hsm_copytool_unregister(struct hsm_copytool_private \*\*priv)
+
+ int llapi_hsm_copytool_get_fd(struct hsm_copytool_private \*ct)
+
+ int llapi_hsm_copytool_recv(struct hsm_copytool_private \*priv,
+ struct hsm_action_list \*\*hal, int \*msgsize)
+
+ struct hsm_action_item \*hai_first(struct hsm_action_list \*hal)
+
+ struct hsm_action_item \*hai_next(struct hsm_action_item \*hai)
+
+ int llapi_hsm_action_begin(struct hsm_copyaction_private \*\*phcp,
+ const struct hsm_copytool_private \*ct, const struct
+ hsm_action_item \*hai, int restore_mdt_index, int
+ restore_open_flags, bool is_error)
+
+ int llapi_hsm_action_end(struct hsm_copyaction_private \*\*phcp,
+ const struct hsm_extent \*he, int hp_flags, int errval)
+
+ int llapi_hsm_action_progress(struct hsm_copyaction_private \*hcp,
+ const struct hsm_extent \*he, __u64 total, int hp_flags)
+
+ int llapi_hsm_action_get_dfid(const struct hsm_copyaction_private \*hcp,
+ lustre_fid \*fid)
+
+ int llapi_hsm_action_get_fd(const struct hsm_copyaction_private \*hcp)
+
+
SEE ALSO
========
git://git.whamcloud.com / fs / lustre-release.git / commitdiff