LLAPI\_HSM\_COPYTOOL\_REGISTER(3) Lustre Library Functions LLAPI\_HSM\_COPYTOOL\_REGISTER(3) # [NAME](#NAME) 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 # [SYNOPSIS](#SYNOPSIS) ``` #include ``` ``` 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](#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)](/man/enterprise-packages/lustre/select.2) or [**poll**(2)](/man/enterprise-packages/lustre/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; /* obsolete and may be ignored */ __u64 hal_flags; __u32 hal_archive_id; /* which archive backend */ __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 */ struct lu_fid hai_fid; /* Lustre FID to operated on */ struct lu_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[]; /* variable length */ }; ``` To iterate through the requests, use **hai\_first** to get the first request, then **hai\_next**. # [RETURN VALUE](#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**](#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, -EAGAIN is immediately returned if no message is available. On error, a negative errno is returned. # [ERRORS](#ERRORS) [**-EINVAL**](#EINVAL) An invalid value was passed, the copytool is not registered, ... [**-ESHUTDOWN**](#ESHUTDOWN) The transport endpoint shutdown. [**-EPROTO**](#EPROTO) Lustre protocol error. [**-EAGAIN**](#EAGAIN) No HSM message is available, and the copytool was set to not block on receives. # [AUTHORS](#AUTHORS) Frank Zago # [AVAILABILITY](#AVAILABILITY) **llapi\_hsm\_copytool\_register()**, **llapi\_hsm\_copytool\_unregister()**, **llapi\_hsm\_copytool\_get\_fd()** and **llapi\_hsm\_copytool\_recv()** are part of the [**lustre**(7)](/man/enterprise-packages/lustre/lustre.7) user application interface library since release 2.4.0. **hai\_first()** and **hai\_next()** are part of the [**lustre**(7)](/man/enterprise-packages/lustre/lustre.7) user application interface library. **hai\_first** was added in release 2.5.0. **hai\_next was added in release 2.0.0.** # [SEE ALSO](#SEE_ALSO) [**llapi\_hsm\_action\_begin**(3)](/man/enterprise-packages/lustre/llapi_hsm_action_begin.3), [**llapi\_hsm\_action\_end**(3)](/man/enterprise-packages/lustre/llapi_hsm_action_end.3), [**llapi\_hsm\_action\_get\_dfid**(3)](/man/enterprise-packages/lustre/llapi_hsm_action_get_dfid.3), [**llapi\_hsm\_action\_get\_fd**(3)](/man/enterprise-packages/lustre/llapi_hsm_action_get_fd.3), [**llapi\_hsm\_action\_progress**(3)](/man/enterprise-packages/lustre/llapi_hsm_action_progress.3), [**lustreapi**(7)](/man/enterprise-packages/lustre/lustreapi.7) See *lhsmtool\_posix.c* in the Lustre sources for a use case of this API. 2024-08-27 Lustre User API --- Document: llapi_hsm_copytool_register(3) from lustre 2.17.59-r2 (Chainguard OS) Source: https://github.com/lustre/lustre-release