lustre/doc/llapi_hsm_action_begin.3

   1 .
   2 .TH LLAPI_HSM_ACTION_BEGIN 3 "2014-09-24" "" "Lustre HSM User API"
   3 .SH NAME
   4 llapi_hsm_action_begin \- Lustre API copytool management
   5 .
   6 .SH SYNOPSIS
   7 .sp
   8 \fB#include <lustre/lustreapi.h>\fP
   9 .sp
  10 \fBint llapi_hsm_action_begin(struct hsm_copyaction_private **\fPphcp\fB,
  11 const struct hsm_copytool_private *\fPct\fB, const struct
  12 hsm_action_item *\fPhai\fB, int\fP restore_mdt_index\fB, int\fP
  13 restore_open_flags\fB, bool\fP is_error\fB)\fP
  14 .sp
  15 \fBint llapi_hsm_action_end(struct hsm_copyaction_private **\fPphcp\fB,
  16 const struct hsm_extent *\fPhe\fB, int\fP hp_flags\fB, int\fP errval\fB)\fP
  17 .sp
  18 \fBint llapi_hsm_action_progress(struct hsm_copyaction_private *\fPhcp\fB,
  19 const struct hsm_extent *\fPhe\fB, __u64\fP total\fB, int\fP hp_flags\fB)\fP
  20 .sp
  21 \fBint llapi_hsm_action_get_dfid(const struct hsm_copyaction_private *\fPhcp\fB,
  22 lustre_fid  *\fPfid\fB)\fP
  23 .sp
  24 \fBint llapi_hsm_action_get_fd(const struct hsm_copyaction_private *\fPhcp\fB)\fP
  25 .SH DESCRIPTION
  26 .sp
  27 When a copytool is ready to process an HSM action received through
  28 \fBllapi_hsm_copytool_recv\fP(), it must first call
  29 \fBllapi_hsm_action_begin\fP() to initialize the internal action
  30 state, stored in \fIphcp\fP\&. \fIct\fP is the opaque copytools handle
  31 previously returned by \fBllapi_hsm_copytool_register\fP(). \fIhai\fP is
  32 the request. \fIrestore_mdt_index\fP and \fIrestore_open_flags\fP are only
  33 used for an \fBHSMA_RESTORE\fP type of request. \fIrestore_mdt_index\fP is
  34 the MDT index on which to create the restored file, or \-1 for
  35 default. If the copytool does not intend to process the request, it
  36 should set \fIis_error\fP to \fBtrue\fP, and then call
  37 \fBllapi_hsm_action_end\fP().
  38 .sp
  39 While performing a copy (i.e. the HSM request is either
  40 \fBHSMA_ARCHIVE\fP or \fBHSMA_RESTORE\fP), the copytool can inform Lustre
  41 of the progress of the operation with \fBllapi_hsm_action_progress\fP(). \fIhe\fP is the interval (\fIoffset\fP, \fIlength\fP) of the data copied. Each
  42 interval must be unique; i.e. there must not be any overlap. \fIlength\fP
  43 is the total length that is expected to be transfered. \fIhp_flags\fP
  44 should be 0. The progress can be checked on any Lustre client by
  45 calling \fBllapi_hsm_current_action\fP(), or by using \fBlfs
  46 hsm_action\fP\&.
  47 .sp
  48 Once the HSM request has been performed, the destination file must be
  49 closed, and \fBllapi_hsm_action_end\fP() must be called to free\-up the
  50 allocated ressources and signal Lustre that the file is now available
  51 to consumers. \fIerrval\fP is set to 0 on success. On error, it must be an
  52 errno, and hp_flags can be set to \fBHP_FLAG_RETRY\fP if the request is
  53 retryable, 0 otherwise. \fIhe\fP is the interval (\fIoffset\fP, \fIlength\fP) of
  54 the data copied. It can be the \fIhai_extent\fP of the HSM request.
  55 .sp
  56 For a restore operation, a volatile file, invisible to ls, is
  57 created. \fBllapi_hsm_action_get_fd\fP() will return a file descriptor
  58 to it. It is the responsibility of the copytool to close the returned
  59 file descriptor when the data transfer is
  60 done. \fBllapi_hsm_action_get_dfid\fP() will return the FID of the volatile
  61 file, which can then be used with \fBllapi_open_by_fid\fP() to open
  62 the file in a different process, or on a different node.
  63 .sp
  64 \fBllapi_hsm_action_get_fd\fP() and \fBllapi_hsm_action_get_dfid\fP()
  65 can be called for an archive operation too. The returned file
  66 descriptor and the FID are from the file to be archived.
  67 .SH RETURN VALUE
  68 .sp
  69 \fBllapi_hsm_action_get_fd\fP() returns a file descriptor on
  70 success. The other functions return 0 on success. All functions return
  71 a negative errno on failure.
  72 .SH ERRORS
  73 .sp
  74 The negative errno can be, but is not limited to:
  75 .TP
  76 .B \fB\-EINVAL\fP An invalid value was passed, the copytool is not
  77 registered, ...
  78 .TP
  79 .B \fB\-ENOMEM\fP Not enough memory to allocate a resource.
  80 .SH SEE ALSO
  81 .sp
  82 \fBllapi_hsm_copytool_register\fP(3), \fBllapi_hsm_copytool_recv\fP(3),
  83 \fBlustreapi\fP(7), \fBlfs\fP(1)
  84 .sp
  85 See \fIlhsmtool_posix.c\fP in the Lustre sources for a use case of this
  86 API.
  87 .SH AUTHOR
  88 Frank Zago
  89 .