lustre/doc/llapi_hsm_copytool_register.rst

   1 ===========================
   2 llapi_hsm_copytool_register
   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_copytool_register(struct hsm_copytool_private \*\***\ priv\ **,
  21 const char \***\ mnt\ **, int** archive_count\ **, int \***\ archives\ **,
  22 int** rfd_flags\ **)**
  23
  24 **int llapi_hsm_copytool_unregister(struct hsm_copytool_private \*\***\ priv
  25 **)**
  26
  27 **int llapi_hsm_copytool_get_fd(struct hsm_copytool_private \***\ ct\ **)**
  28
  29 **int llapi_hsm_copytool_recv(struct hsm_copytool_private \***\ priv\ **,
  30 **struct hsm_action_list \*\***\ hal\ **, int \***\ msgsize\ **)**
  31
  32 **struct hsm_action_item \*hai_first(struct hsm_action_list \***\ hal\ **)**
  33
  34 **struct hsm_action_item \*hai_next(struct hsm_action_item \***\ hai\ **)**
  35
  36
  37 DESCRIPTION
  38 ===========
  39
  40 To receive HSM requests from a Lustre filesystem, a copytool
  41 application must register with Lustre by calling
  42 **llapi_hsm_copytool_register**\ (). The mountpoint of the Lustre
  43 filesystem to monitor is indicated by *mnt*. *archives* is an array
  44 with up to 32 elements indicating which archive IDs to register
  45 for. Each element is a number from 1 to 32. *archive_count* is the
  46 number of valid elements in the *archive* array. If an element in
  47 *archives* is 0, or if *archive_count* is 0, then all archives will be
  48 monitored. *rfd_flags* determines whether **llapi_hsm_copytool_recv**
  49 will be blocking, with 0, or non-blocking, with O_NONBLOCK.
  50
  51 **llapi_hsm_copytool_register** returns *priv*, an opaque
  52 pointer that must be used with the other functions.
  53
  54 **llapi_hsm_copytool_unregister** unregisters a copytool. *priv* is
  55 the opaque handle returned by **llapi_hsm_copytool_register**.
  56
  57 **llapi_hsm_copytool_get_fd** returns the file descriptor used by the
  58 library to communicate with the kernel. This descriptor is only
  59 intended to be used with **select(2)** or **poll(2)**. *rfd_flags*
  60 should have been set to O_NONBLOCK.
  61
  62 To receive the requests, the application has to call
  63 **llapi_hsm_copytool_recv**. When it returns 0, a message is available
  64 in *hal*, and its size in bytes is returned in *msgsize*. *hal* points
  65 to a buffer allocated by the Lustre library. It contains one or more
  66 HSM requests. This buffer is valid until the next call to
  67 **llapi_hsm_copytool_recv**.
  68
  69 *hal* is composed of a header of type *struct hsm_action_list*
  70 followed by one or several HSM requests of type *struct
  71 hsm_action_item*::
  72
  73     struct hsm_action_list {
  74        __u32 hal_version;
  75        __u32 hal_count;         /* number of hai's to follow */
  76        __u64 hal_compound_id;   /* returned by coordinator */
  77        __u64 hal_flags;
  78        __u32 hal_archive_id;    /* which archive backend */
  79        __u32 padding1;
  80        char hal_fsname[0];      /* null-terminated name of filesystem */
  81     };
  82
  83     struct hsm_action_item {
  84         __u32      hai_len;     /* valid size of this struct */
  85         __u32      hai_action;  /* hsm_copytool_action, but use known size */
  86         lustre_fid hai_fid;     /* Lustre FID to operated on */
  87         lustre_fid hai_dfid;    /* fid used for data access */
  88         struct hsm_extent hai_extent;  /* byte range to operate on */
  89         __u64      hai_cookie;  /* action cookie from coordinator */
  90         __u64      hai_gid;     /* grouplock id */
  91         char       hai_data[0]; /* variable length */
  92     };
  93
  94 To iterate through the requests, use **hai_first** to get the first
  95 request, then **hai_next**.
  96
  97
  98 RETURN VALUE
  99 ============
 100
 101 **llapi_hsm_copytool_register** and **llapi_hsm_copytool_unregister**
 102 return 0 on success. On error, a negative errno is returned.
 103
 104 **llapi_hsm_copytool_get_fd** returns the file descriptor associated
 105  with the register copytool. On error, a negative errno is returned.
 106
 107 **llapi_hsm_copytool_recv** returns 0 when a message is available. If
 108 the copytool was set to non-blocking operation, -EWOULDBLOCK is
 109 immediately returned if no message is available. On error, a negative
 110 errno is returned.
 111
 112
 113 ERRORS
 114 ======
 115
 116 **-EINVAL** An invalid value was passed, the copytool is not
 117    registered, ...
 118
 119 **-ESHUTDOWN** The transport endpoint shutdown.
 120
 121 **-EPROTO** Lustre protocol error.
 122
 123 **-EWOULDBLOCK** No HSM message is available, and the copytool was set
 124 to not block on receives.
 125
 126
 127 SEE ALSO
 128 ========
 129
 130 **llapi_hsm_action_begin**\ (3), **llapi_hsm_action_end**\ (3),
 131 **llapi_hsm_action_progress**\ (3), **llapi_hsm_action_get_dfid**\ (3),
 132 **llapi_hsm_action_get_fd**\ (3), **lustreapi**\ (7)
 133
 134 See *lhsmtool_posix.c* in the Lustre sources for a use case of this
 135 API.