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 .