lustre/doc/llapi_hsm_action_begin.rst

   1 ======================
   2 llapi_hsm_action_begin
   3 ======================
   4
   5 ------------------------------
   6 Lustre API copytool management
   7 ------------------------------
   8
   9 :Author: Frank Zago
  10 :Date:   2014-09-24
  11 :Manual section: 3
  12 :Manual group: Lustre HSM User API
  13
  14
  15 SYNOPSIS
  16 ========
  17
  18 **#include <lustre/lustreapi.h>**
  19
  20 **int llapi_hsm_action_begin(struct hsm_copyaction_private \*\***\ phcp\ **,
  21 const struct hsm_copytool_private \***\ ct\ **, const struct
  22 hsm_action_item \***\ hai\ **, int** restore_mdt_index\ **, int**
  23 restore_open_flags\ **, bool** is_error\ **)**
  24
  25 **int llapi_hsm_action_end(struct hsm_copyaction_private \*\***\ phcp\ **,
  26 const struct hsm_extent \***\ he\ **, int** hp_flags\ **, int** errval\ **)**
  27
  28 **int llapi_hsm_action_progress(struct hsm_copyaction_private \***\ hcp\ **,
  29 const struct hsm_extent \***\ he\ **, __u64** total\ **, int** hp_flags\ **)**
  30
  31 **int llapi_hsm_action_get_dfid(const struct hsm_copyaction_private \***\ hcp\ **,
  32 lustre_fid  \***\ fid\ **)**
  33
  34 **int llapi_hsm_action_get_fd(const struct hsm_copyaction_private \***\ hcp\ **)**
  35
  36
  37 DESCRIPTION
  38 ===========
  39
  40 When a copytool is ready to process an HSM action received through
  41 **llapi_hsm_copytool_recv**\ (), it must first call
  42 **llapi_hsm_action_begin**\ () to initialize the internal action
  43 state, stored in *phcp*. *ct* is the opaque copytools handle
  44 previously returned by **llapi_hsm_copytool_register**\ (). *hai* is
  45 the request. *restore_mdt_index* and *restore_open_flags* are only
  46 used for an **HSMA_RESTORE** type of request. *restore_mdt_index* is
  47 the MDT index on which to create the restored file, or -1 for
  48 default. If the copytool does not intend to process the request, it
  49 should set *is_error* to **true**, and then call
  50 **llapi_hsm_action_end**\ ().
  51
  52 While performing a copy (i.e. the HSM request is either
  53 **HSMA_ARCHIVE** or **HSMA_RESTORE**), the copytool can inform Lustre
  54 of the progress of the operation with **llapi_hsm_action_progress**\
  55 (). *he* is the interval (*offset*, *length*) of the data copied. Each
  56 interval must be unique; i.e. there must not be any overlap. *length*
  57 is the total length that is expected to be transfered. *hp_flags*
  58 should be 0. The progress can be checked on any Lustre client by
  59 calling **llapi_hsm_current_action**\ (), or by using **lfs
  60 hsm_action**.
  61
  62 Once the HSM request has been performed, the destination file must be
  63 closed, and **llapi_hsm_action_end**\ () must be called to free-up the
  64 allocated ressources and signal Lustre that the file is now available
  65 to consumers. *errval* is set to 0 on success. On error, it must be an
  66 errno, and hp_flags can be set to **HP_FLAG_RETRY** if the request is
  67 retryable, 0 otherwise. *he* is the interval (*offset*, *length*) of
  68 the data copied. It can be the *hai_extent* of the HSM request.
  69
  70 For a restore operation, a volatile file, invisible to ls, is
  71 created. **llapi_hsm_action_get_fd**\ () will return a file descriptor
  72 to it. It is the responsibility of the copytool to close the returned
  73 file descriptor when the data transfer is
  74 done. **llapi_hsm_action_get_dfid**\ () will return the FID of the volatile
  75 file, which can then be used with **llapi_open_by_fid**\ () to open
  76 the file in a different process, or on a different node.
  77
  78 **llapi_hsm_action_get_fd**\ () and **llapi_hsm_action_get_dfid**\ ()
  79 can be called for an archive operation too. The returned file
  80 descriptor and the FID are from the file to be archived.
  81
  82
  83 RETURN VALUE
  84 ============
  85
  86 **llapi_hsm_action_get_fd**\ () returns a file descriptor on
  87 success. The other functions return 0 on success. All functions return
  88 a negative errno on failure.
  89
  90
  91 ERRORS
  92 ======
  93
  94 The negative errno can be, but is not limited to:
  95
  96 **-EINVAL** An invalid value was passed, the copytool is not
  97    registered, ...
  98
  99 **-ENOMEM** Not enough memory to allocate a resource.
 100
 101
 102 SEE ALSO
 103 ========
 104
 105 **llapi_hsm_copytool_register**\ (3), **llapi_hsm_copytool_recv**\ (3),
 106 **lustreapi**\ (7), **lfs**\ (1)
 107
 108 See *lhsmtool_posix.c* in the Lustre sources for a use case of this
 109 API.