LLAPI_HSM_COPYTOOL_REGISTER(3)

📦 version 2.17.58, in ubuntu stonking

💖 LLAPI_HSM_COPYTOOL_REGISTER(3) — Lustre Library Functions 💖

okay bestie, so this is a section 3 manpage from the Lustre Library Functions manual, and it's basically the group chat for copytool management. If you've ever needed a copytool to talk to a Lustre filesystem about HSM stuff, this is your page. Sit down, hydrate, let's go 🫶

✨ NAME ✨

llapi_hsm_copytool_register, llapi_hsm_copytool_unregister, llapi_hsm_copytool_get_fd, llapi_hsm_copytool_recv, hai_first, hai_next — Lustre API copytool management. that's the whole squad, together, iconic.

🌸 SYNOPSIS 🌸

#include <lustre/lustreapi.h>

int llapi_hsm_copytool_register(struct hsm_copytool_private **priv,
                                const char *mnt, int archive_count,
                                int *archives, int rfd_flags);

int llapi_hsm_copytool_unregister(struct hsm_copytool_private **priv);

int llapi_hsm_copytool_get_fd(struct hsm_copytool_private *ct);

int llapi_hsm_copytool_recv(struct hsm_copytool_private *priv,
                            struct hsm_action_list **hal,
                            int *msgsize);

struct hsm_action_item *hai_first(struct hsm_action_list *hal);

struct hsm_action_item *hai_next(struct hsm_action_item *hai);

🦋 DESCRIPTION 🦋

so. if your copytool app wants to receive HSM requests from a Lustre filesystem, it literally has to register with Lustre first, and that's a call to llapi_hsm_copytool_register(). no registration, no requests. periodt 💅

  • mnt — the mountpoint of the Lustre filesystem you're monitoring, bestie. that's the one you're watching.
  • archives — an array with up to 32 elements, and each one says which archive IDs to register for. every element is a number from 1 to 32.
  • archive_count — the number of valid elements in that archive array. like, don't count the garbage at the end, ok?
  • if any element in archives is 0, or if archive_count is 0, then all archives will be monitored. (yup, zero means everything, the way that works out 💀)
  • rfd_flags — decides whether llapi_hsm_copytool_recv is blocking, with 0, or non-blocking, with O_NONBLOCK.

llapi_hsm_copytool_register hands you back priv, an opaque pointer that you have to use with all the other functions. it's giving ✨main character handle✨ — you don't look inside it, you just carry it around.

llapi_hsm_copytool_unregister unregisters a copytool. priv here is that same opaque handle that llapi_hsm_copytool_register returned. bye bestie, we're done here 🎀

llapi_hsm_copytool_get_fd returns the file descriptor the library uses to communicate with the kernel. heads up: this descriptor is only intended to be used with select(2) or poll(2). that's it. don't get creative. and rfd_flags should have been set to O_NONBLOCK. no cap.

to actually receive the requests, your app has to call llapi_hsm_copytool_recv. when it returns 0, there's a message available in hal, and its size in bytes comes back in msgsize. hal points to a buffer allocated by the Lustre library — allocated by them, not you, so don't you dare free it 🙈 — and it contains one or more HSM requests. this buffer is valid until the next call to llapi_hsm_copytool_recv. so use it now or lose it, fr fr.

hal is made of a header of type struct hsm_action_list followed by one or several HSM requests of type struct hsm_action_item:

struct hsm_action_list {
   __u32 hal_version;
   __u32 hal_count;         /* number of hai's to follow */
   __u64 hal_compound_id;   /* obsolete and may be ignored */
   __u64 hal_flags;
   __u32 hal_archive_id;    /* which archive backend */
   __u32 padding1;
   char hal_fsname[];       /* null-terminated name of filesystem */
};

struct hsm_action_item {
    __u32      hai_len;     /* valid size of this struct */
    __u32      hai_action;  /* hsm_copytool_action, but use known size */
    struct lu_fid hai_fid;     /* Lustre FID to operated on */
    struct lu_fid hai_dfid;    /* fid used for data access */
    struct hsm_extent hai_extent;  /* byte range to operate on */
    __u64      hai_cookie;  /* action cookie from coordinator */
    __u64      hai_gid;     /* grouplock id */
    char       hai_data[];  /* variable length */
};

and to iterate through all those requests? use hai_first to grab the first one, then keep calling hai_next. that's the lil scroll of doom, but manageable 🧚

👑 RETURN VALUE 👑

llapi_hsm_copytool_register and llapi_hsm_copytool_unregister return 0 on success. on error, a negative errno is returned. (negative errno is the vibe check failing, basically.)

llapi_hsm_copytool_get_fd

  • returns the file descriptor associated with the registered copytool. on error, a negative errno is returned.

llapi_hsm_copytool_recv returns 0 when a message is available. if the copytool was set to non-blocking operation, -EAGAIN is immediately returned when no message is available. on error, a negative errno is returned.

💀 ERRORS 💀

  • -EINVAL — an invalid value was passed, the copytool is not registered, ...
  • -ESHUTDOWN — the transport endpoint shutdown. 💀
  • -EPROTO — Lustre protocol error.
  • -EAGAIN — no HSM message is available, and the copytool was set to not block on receives.
yes bestie, that ... in -EINVAL is literally in the original. we don't make the rules, we just report them.

🎀 AUTHORS 🎀

Frank Zago — shoutout to the icon who wrote this 👑

🌈 AVAILABILITY 🌈

llapi_hsm_copytool_register(), llapi_hsm_copytool_unregister(), llapi_hsm_copytool_get_fd() and llapi_hsm_copytool_recv() are part of the lustre(7) user application interface library since release 2.4.0.

hai_first() and hai_next() are part of the lustre(7) user application interface library.

  • hai_first was added in release 2.5.0.
  • hai_next was added in release 2.0.0.

(the way they dropped in different releases and still ended up in the same friend group ✨)

💅 SEE ALSO 💅

also, real talk: see lhsmtool_posix.c in the Lustre sources for a use case of this API. iykyk 🍓

and that's the page bestie!! 🥳 this was Lustre User API, dated 2024-08-27 — drink some water, go write that copytool, and slay ✨💜🌺

📦 where this page comes from