1 ===========================
2 llapi_hsm_copytool_register
3 ===========================
5 ------------------------------
6 Lustre API copytool management
7 ------------------------------
12 :Manual group: Lustre HSM User API
18 **#include <lustre/lustreapi.h>**
20 **int llapi_hsm_copytool_register(struct hsm_copytool_private \*\***\ priv\ **,
21 const char \***\ mnt\ **, int** archive_count\ **, int \***\ archives\ **,
22 int** rfd_flags\ **)**
24 **int llapi_hsm_copytool_unregister(struct hsm_copytool_private \*\***\ priv
27 **int llapi_hsm_copytool_get_fd(struct hsm_copytool_private \***\ ct\ **)**
29 **int llapi_hsm_copytool_recv(struct hsm_copytool_private \***\ priv\ **,
30 **struct hsm_action_list \*\***\ hal\ **, int \***\ msgsize\ **)**
32 **struct hsm_action_item \*hai_first(struct hsm_action_list \***\ hal\ **)**
34 **struct hsm_action_item \*hai_next(struct hsm_action_item \***\ hai\ **)**
40 To receive HSM requests from a Lustre filesystem, a copytool
41 application must register with Lustre by calling
42 **llapi_hsm_copytool_register**\ (). The mountpoint of the Lustre
43 filesystem to monitor is indicated by *mnt*. *archives* is an array
44 with up to 32 elements indicating which archive IDs to register
45 for. Each element is a number from 1 to 32. *archive_count* is the
46 number of valid elements in the *archive* array. If an element in
47 *archives* is 0, or if *archive_count* is 0, then all archives will be
48 monitored. *rfd_flags* determines whether **llapi_hsm_copytool_recv**
49 will be blocking, with 0, or non-blocking, with O_NONBLOCK.
51 **llapi_hsm_copytool_register** returns *priv*, an opaque
52 pointer that must be used with the other functions.
54 **llapi_hsm_copytool_unregister** unregisters a copytool. *priv* is
55 the opaque handle returned by **llapi_hsm_copytool_register**.
57 **llapi_hsm_copytool_get_fd** returns the file descriptor used by the
58 library to communicate with the kernel. This descriptor is only
59 intended to be used with **select(2)** or **poll(2)**. *rfd_flags*
60 should have been set to O_NONBLOCK.
62 To receive the requests, the application has to call
63 **llapi_hsm_copytool_recv**. When it returns 0, a message is available
64 in *hal*, and its size in bytes is returned in *msgsize*. *hal* points
65 to a buffer allocated by the Lustre library. It contains one or more
66 HSM requests. This buffer is valid until the next call to
67 **llapi_hsm_copytool_recv**.
69 *hal* is composed of a header of type *struct hsm_action_list*
70 followed by one or several HSM requests of type *struct
73 struct hsm_action_list {
75 __u32 hal_count; /* number of hai's to follow */
76 __u64 hal_compound_id; /* returned by coordinator */
78 __u32 hal_archive_id; /* which archive backend */
80 char hal_fsname[0]; /* null-terminated name of filesystem */
83 struct hsm_action_item {
84 __u32 hai_len; /* valid size of this struct */
85 __u32 hai_action; /* hsm_copytool_action, but use known size */
86 lustre_fid hai_fid; /* Lustre FID to operated on */
87 lustre_fid hai_dfid; /* fid used for data access */
88 struct hsm_extent hai_extent; /* byte range to operate on */
89 __u64 hai_cookie; /* action cookie from coordinator */
90 __u64 hai_gid; /* grouplock id */
91 char hai_data[0]; /* variable length */
94 To iterate through the requests, use **hai_first** to get the first
95 request, then **hai_next**.
101 **llapi_hsm_copytool_register** and **llapi_hsm_copytool_unregister**
102 return 0 on success. On error, a negative errno is returned.
104 **llapi_hsm_copytool_get_fd** returns the file descriptor associated
105 with the register copytool. On error, a negative errno is returned.
107 **llapi_hsm_copytool_recv** returns 0 when a message is available. If
108 the copytool was set to non-blocking operation, -EWOULDBLOCK is
109 immediately returned if no message is available. On error, a negative
116 **-EINVAL** An invalid value was passed, the copytool is not
119 **-ESHUTDOWN** The transport endpoint shutdown.
121 **-EPROTO** Lustre protocol error.
123 **-EWOULDBLOCK** No HSM message is available, and the copytool was set
124 to not block on receives.
130 **llapi_hsm_action_begin**\ (3), **llapi_hsm_action_end**\ (3),
131 **llapi_hsm_action_progress**\ (3), **llapi_hsm_action_get_dfid**\ (3),
132 **llapi_hsm_action_get_fd**\ (3), **lustreapi**\ (7)
134 See *lhsmtool_posix.c* in the Lustre sources for a use case of this