Whamcloud - gitweb
LU-6142 uapi: Get rid of lustre_fid typedef
[fs/lustre-release.git] / lustre / doc / llapi_hsm_copytool_register.3
1 .
2 .TH LLAPI_HSM_COPYTOOL_REGISTER 3 "2014-09-24" "" "Lustre HSM User API"
3 .SH NAME
4 llapi_hsm_copytool_register \- Lustre API copytool management
5 .
6 .nr rst2man-indent-level 0
7 .
8 .de1 rstReportMargin
9 \\$1 \\n[an-margin]
10 level \\n[rst2man-indent-level]
11 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
12 -
13 \\n[rst2man-indent0]
14 \\n[rst2man-indent1]
15 \\n[rst2man-indent2]
16 ..
17 .de1 INDENT
18 .\" .rstReportMargin pre:
19 . RS \\$1
20 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
21 . nr rst2man-indent-level +1
22 .\" .rstReportMargin post:
23 ..
24 .de UNINDENT
25 . RE
26 .\" indent \\n[an-margin]
27 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
28 .nr rst2man-indent-level -1
29 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
30 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
31 ..
32 .SH SYNOPSIS
33 .sp
34 \fB#include <lustre/lustreapi.h>\fP
35 .sp
36 \fBint llapi_hsm_copytool_register(struct hsm_copytool_private **\fPpriv\fB,
37 const char *\fPmnt\fB, int\fP archive_count\fB, int *\fParchives\fB,
38 int\fP rfd_flags\fB)\fP
39 .sp
40 \fBint llapi_hsm_copytool_unregister(struct hsm_copytool_private **\fPpriv
41 \fB)\fP
42 .sp
43 \fBint llapi_hsm_copytool_get_fd(struct hsm_copytool_private *\fPct\fB)\fP
44 .sp
45 \fBint llapi_hsm_copytool_recv(struct hsm_copytool_private *\fPpriv\fB,
46 **struct hsm_action_list **\fPhal\fB, int *\fPmsgsize\fB)\fP
47 .sp
48 \fBstruct hsm_action_item *hai_first(struct hsm_action_list *\fPhal\fB)\fP
49 .sp
50 \fBstruct hsm_action_item *hai_next(struct hsm_action_item *\fPhai\fB)\fP
51 .SH DESCRIPTION
52 .sp
53 To receive HSM requests from a Lustre filesystem, a copytool
54 application must register with Lustre by calling
55 \fBllapi_hsm_copytool_register\fP(). The mountpoint of the Lustre
56 filesystem to monitor is indicated by \fImnt\fP\&. \fIarchives\fP is an array
57 with up to 32 elements indicating which archive IDs to register
58 for. Each element is a number from 1 to 32. \fIarchive_count\fP is the
59 number of valid elements in the \fIarchive\fP array. If an element in
60 \fIarchives\fP is 0, or if \fIarchive_count\fP is 0, then all archives will be
61 monitored. \fIrfd_flags\fP determines whether \fBllapi_hsm_copytool_recv\fP
62 will be blocking, with 0, or non\-blocking, with O_NONBLOCK.
63 .sp
64 \fBllapi_hsm_copytool_register\fP returns \fIpriv\fP, an opaque
65 pointer that must be used with the other functions.
66 .sp
67 \fBllapi_hsm_copytool_unregister\fP unregisters a copytool. \fIpriv\fP is
68 the opaque handle returned by \fBllapi_hsm_copytool_register\fP\&.
69 .sp
70 \fBllapi_hsm_copytool_get_fd\fP returns the file descriptor used by the
71 library to communicate with the kernel. This descriptor is only
72 intended to be used with \fBselect(2)\fP or \fBpoll(2)\fP\&. \fIrfd_flags\fP
73 should have been set to O_NONBLOCK.
74 .sp
75 To receive the requests, the application has to call
76 \fBllapi_hsm_copytool_recv\fP\&. When it returns 0, a message is available
77 in \fIhal\fP, and its size in bytes is returned in \fImsgsize\fP\&. \fIhal\fP points
78 to a buffer allocated by the Lustre library. It contains one or more
79 HSM requests. This buffer is valid until the next call to
80 \fBllapi_hsm_copytool_recv\fP\&.
81 .sp
82 \fIhal\fP is composed of a header of type \fIstruct hsm_action_list\fP
83 followed by one or several HSM requests of type \fIstruct
84 hsm_action_item\fP:
85 .INDENT 0.0
86 .INDENT 3.5
87 .sp
88 .nf
89 .ft C
90 struct hsm_action_list {
91    __u32 hal_version;
92    __u32 hal_count;         /* number of hai\(aqs to follow */
93    __u64 hal_compound_id;   /* returned by coordinator */
94    __u64 hal_flags;
95    __u32 hal_archive_id;    /* which archive backend */
96    __u32 padding1;
97    char hal_fsname[0];      /* null\-terminated name of filesystem */
98 };
99
100 struct hsm_action_item {
101     __u32      hai_len;     /* valid size of this struct */
102     __u32      hai_action;  /* hsm_copytool_action, but use known size */
103     struct lu_fid hai_fid;     /* Lustre FID to operated on */
104     struct lu_fid hai_dfid;    /* fid used for data access */
105     struct hsm_extent hai_extent;  /* byte range to operate on */
106     __u64      hai_cookie;  /* action cookie from coordinator */
107     __u64      hai_gid;     /* grouplock id */
108     char       hai_data[0]; /* variable length */
109 };
110 .ft P
111 .fi
112 .UNINDENT
113 .UNINDENT
114 .sp
115 To iterate through the requests, use \fBhai_first\fP to get the first
116 request, then \fBhai_next\fP\&.
117 .SH RETURN VALUE
118 .sp
119 \fBllapi_hsm_copytool_register\fP and \fBllapi_hsm_copytool_unregister\fP
120 return 0 on success. On error, a negative errno is returned.
121 .INDENT 0.0
122 .TP
123 .B \fBllapi_hsm_copytool_get_fd\fP returns the file descriptor associated
124 with the register copytool. On error, a negative errno is returned.
125 .UNINDENT
126 .sp
127 \fBllapi_hsm_copytool_recv\fP returns 0 when a message is available. If
128 the copytool was set to non\-blocking operation, \-EWOULDBLOCK is
129 immediately returned if no message is available. On error, a negative
130 errno is returned.
131 .SH ERRORS
132 .INDENT 0.0
133 .TP
134 .B \fB\-EINVAL\fP An invalid value was passed, the copytool is not
135 registered, ...
136 .UNINDENT
137 .sp
138 \fB\-ESHUTDOWN\fP The transport endpoint shutdown.
139 .sp
140 \fB\-EPROTO\fP Lustre protocol error.
141 .sp
142 \fB\-EWOULDBLOCK\fP No HSM message is available, and the copytool was set
143 to not block on receives.
144 .SH SEE ALSO
145 .sp
146 \fBllapi_hsm_action_begin\fP(3), \fBllapi_hsm_action_end\fP(3),
147 \fBllapi_hsm_action_progress\fP(3), \fBllapi_hsm_action_get_dfid\fP(3),
148 \fBllapi_hsm_action_get_fd\fP(3), \fBlustreapi\fP(7)
149 .sp
150 See \fIlhsmtool_posix.c\fP in the Lustre sources for a use case of this
151 API.
152 .SH AUTHOR
153 Frank Zago
154 .