2 .TH LLAPI_HSM_ACTION_BEGIN 3 "2014-09-24" "" "Lustre HSM User API"
4 llapi_hsm_action_begin \- Lustre API copytool management
8 \fB#include <lustre/lustreapi.h>\fP
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
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
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
21 \fBint llapi_hsm_action_get_dfid(const struct hsm_copyaction_private *\fPhcp\fB,
22 lustre_fid *\fPfid\fB)\fP
24 \fBint llapi_hsm_action_get_fd(const struct hsm_copyaction_private *\fPhcp\fB)\fP
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().
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
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.
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.
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.
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.
74 The negative errno can be, but is not limited to:
76 .B \fB\-EINVAL\fP An invalid value was passed, the copytool is not
79 .B \fB\-ENOMEM\fP Not enough memory to allocate a resource.
82 \fBllapi_hsm_copytool_register\fP(3), \fBllapi_hsm_copytool_recv\fP(3),
83 \fBlustreapi\fP(7), \fBlfs\fP(1)
85 See \fIlhsmtool_posix.c\fP in the Lustre sources for a use case of this