LLAPI_CHANGELOG_START(3)

📦 version 2.17.58, in ubuntu stonking

💖 LLAPI_CHANGELOG_START 💖

okay bestie, gather round, because this one is from the Lustre Library Functions manual and it's literally the glow-up tutorial for reading MDT changelogs. yes, the whole family: llapi_changelog_start, llapi_changelog_start_user, llapi_changelog_set_xflags, and llapi_changelog_fini — they initialize and clean a read instance for MDT changelogs. it's giving "set up your little reading corner, then tidy it up when you're done." 🎀

✨ SYNOPSIS ✨

#include <lustre/lustreapi.h>

int llapi_changelog_start(void **priv, enum changelog_send_flag flags,
                          const char *device, long long startrec);

int llapi_changelog_start_user(void **priv, enum changelog_send_flag flags,
                               const char *device, const char *username,
                               __u64 mask, long long startrec);

int llapi_changelog_set_xflags(void *priv,
                               enum changelog_send_extra_flag extra_flags);

int llapi_changelog_fini(void **priv);

🌸 DESCRIPTION 🌸

so llapi_changelog_start() spins up a brand new instance priv for reading MDT changelogs. it opens the changelog char device that matches the MDT name you hand it in device — like, say, "lustrefs-MDT0000". 🦋

you can pick where the reading begins with the startrec record number. llapi_changelog_recv() will grab changelog records with numbers greater than or equal to startrec. and if you pass 0, that means all the records get read. no skips, no crumbs. 💅

some options can be passed along to llapi_changelog_start() through the flags mask.

enum changelog_send_flag values:

  • CHANGELOG_FLAG_FOLLOW
  • CHANGELOG_FLAG_BLOCK
  • CHANGELOG_FLAG_JOBID
  • CHANGELOG_FLAG_EXTRA_FLAGS

CHANGELOG_FLAG_FOLLOW : turns on changelog follow mode: llapi_changelog_recv() will not return once all records have been read. instead it just blocks until a new record shows up. the vibe here is that you never have to restart an instance and re-scan for newer changelogs — it's already sitting there waiting, main character energy. 😌

CHANGELOG_FLAG_BLOCK : deprecated since Lustre 2.10. 💀

CHANGELOG_FLAG_JOBID : packs jobid into the changelog records if it's available.

CHANGELOG_FLAG_EXTRA_FLAG : packs additional flag bits into the changelog record.

llapi_changelog_start_user() is basically llapi_changelog_start()'s sibling — it also initializes a new instance priv to read MDT changelogs, except it comes with user-specific filtering, including username and mask. 🫶

the username parameter is the changelog username or ID, like "cl1", "cl1-user", "1", or "user".

the mask parameter is the filtering mask, in numeric form. and if mask is 0, then the user's registered MASK that was specified to lctl-changelog_register(8) gets used instead.

the llapi_changelog_set_xflags() function sets additional changelog flags via the extra_flags mask on the instance priv. heads up though — to actually use those extra flags, CHANGELOG_FLAG_EXTRA_FLAG has to be set by llapi_changelog_start() on the flags parameter. no flag, no extra flag. periodt. ✨

enum changelog_send_extra_flag values:

  • CHANGELOG_EXTRA_FLAG_UIDGID
  • CHANGELOG_EXTRA_FLAG_NID
  • CHANGELOG_EXTRA_FLAG_OMODE
  • CHANGELOG_EXTRA_FLAG_XATTR

CHANGELOG_EXTRA_FLAG_UIDGID : packs uid/gid into the changelog record

CHANGELOG_EXTRA_FLAG_NID : packs nid into the changelog record

CHANGELOG_EXTRA_FLAG_OMODE : packs open mode into the changelog record

CHANGELOG_EXTRA_FLAG_XATTR : packs the xattr name into the changelog record

and finally, llapi_changelog_fini() closes the MDT's changelog char device and frees the internal pointers for the instance priv. the cleanup era. 🧹💖

🌈 RETURN VALUES 🌈

returns 0 on success, or a negative errno value when it fails. simple as that, bestie.

💀 ERRORS 💀

  • -ENOMEM — not enough memory to complete the operation. 😭
  • -EINVAL — one or more invalid arguments were given.
  • -ENOENT — MDT's changelog char device not found. is the Lustre FS even mounted?? 🙈
  • -EACCES — not enough permissions to open the changelog char device. by default, the device is only accessible to the root user. 👑

🍓 EXAMPLE 🍓

to register a user to watch file and directory creation and removal:

char *mdd = "testfs-MDT0000";
long long startrec = 0;
char *name = "dirwatch";
char *mask_str = "rmdir,mkdir,creat,unlnk";
__u64 mask = CHANGELOG_DEFMASK;
void *changelog_priv;
struct changelog_rec *rec;

/* convert mask string to numeric value */
rc = llapi_convert_str2mask(mask_str, changelog_type2str, &mask,
                        CHANGELOG_MINMASK, CHANGELOG_ALLMASK,
                        CHANGELOG_DEFMASK);

/* register a new Changelog consumer with a name and mask */
rc = llapi_changelog_start_user(&changelog_priv,
                        CHANGELOG_FLAG_BLOCK | CHANGELOG_FLAG_EXTRA_FLAGS |
                        CHANGELOG_FLAG_NID_BE | CHANGELOG_FLAG_JOBID,
                        mdd, name, mask, startrec);
rc = llapi_changelog_set_xflags(changelog_priv,
                                CHANGELOG_EXTRA_FLAG_UIDGID |
                                CHANGELOG_EXTRA_FLAG_NID |
                                CHANGELOG_EXTRA_FLAG_OMODE |
                                CHANGELOG_EXTRA_FLAG_XATTR);

while ((rc = llapi_changelog_recv(changelog_priv, &rec)) == 0) {
        /* process changelog records */
        llapi_changelog_free(&rec);
}

llapi_changelog_fini(&changelog_priv);

🦋 AVAILABILITY 🦋

llapi_changelog_start() and llapi_changelog_fini() have been part of the lustre(7) user application interface library since release 2.0.0, llapi_changelog_set_xflags() since release 2.11.0, and llapi_changelog_start_user() since release 2.18.0. look at them, growing up so fast 🥹

👑 SEE ALSO 👑

lfs-changelog(1), llapi_changelog_clear(3), llapi_changelog_get_fd(3), llapi_changelog_in_buf(3), llapi_changelog_recv(3), llapi_changelog_start_user(3), llapi_convert_str2mask(3), lustreapi(7), lctl-changelog_register(8)

k that's the whole page bestie, mwah 💖 this icon of a manpage is brought to you by the Lustre User API, dated 2025-11-25, and it lives at section 3 of the manual under the name LLAPI_CHANGELOG_START. go read bughead lore or something, ily, bye ✨

📦 where this page comes from