LLAPI\_HSM\_ACTION\_BEGIN(3) Lustre Library Functions LLAPI\_HSM\_ACTION\_BEGIN(3)

# [NAME](#NAME)

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

# [SYNOPSIS](#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](#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 resources 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](#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](#ERRORS)

The negative errno can be, but is not limited to:

[**-EINVAL**](#EINVAL)

An invalid value was passed, the copytool is not registered, ...

[**-ENOMEM**](#ENOMEM)

Not enough memory to allocate a resource.

# [AUTHORS](#AUTHORS)

Frank Zago

# [AVAILABILITY](#AVAILABILITY)

**llapi\_hsm\_action\_begin(),** **llapi\_hsm\_action\_end(),** **llapi\_hsm\_action\_progress(),** **llapi\_hsm\_action\_get\_dfid()** and **llapi\_hsm\_action\_get\_fd()** are part of the [**lustre**(7)](/man/enterprise-packages/lustre/lustre.7) user application interface library since release 2.4.0

# [SEE ALSO](#SEE_ALSO)

[**lfs**(1)](/man/enterprise-packages/lustre/lfs.1), [**llapi\_hsm\_copytool\_recv**(3)](/man/enterprise-packages/lustre/llapi_hsm_copytool_recv.3), [**llapi\_hsm\_copytool\_register**(3)](/man/enterprise-packages/lustre/llapi_hsm_copytool_register.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_action_progress(3) from lustre 2.17.59-r2 (Chainguard OS)
Source: https://github.com/lustre/lustre-release