.TH LLAPI_CHANGELOG_START 3 2026-09-12 "Lustre User API" "Lustre Library Functions" .SH NAME llapi_changelog_start, llapi_changelog_start_user, llapi_changelog_set_xflags, llapi_changelog_fini \- Initialize and clean a read instance for MDT changelogs .SH SYNOPSIS .nf .B #include .PP .BI "int llapi_changelog_start(void **" priv ", enum changelog_send_flag " flags , .BI " const char *" device ", long long " startrec ");" .PP .BI "int llapi_changelog_start_user(void **" priv ", enum changelog_send_flag " flags , .BI " const char *" device ", const char *" username , .BI " __u64 " mask ", long long " startrec ");" .PP .BI "int llapi_changelog_set_xflags(void *" priv, .BI " enum changelog_send_extra_flag " extra_flags ");" .PP .BI "int llapi_changelog_fini(void **" priv ");" .fi .SH DESCRIPTION The function .B llapi_changelog_start() initializes a new instance .I priv to read MDT changelogs. It opens the changelog char device corresponding to the MDT's name given by .I device (e.g: "lustrefs-MDT0000"). .P A changelog starting point can be specified with .I startrec record number. .B llapi_changelog_recv() will get changelog records with numbers greater or equal than .IR startrec . 0 value means that all records will be read. .PP Some options can be passed to .B llapi_changelog_start() with .I flags mask. .PP .B enum changelog_send_flag values: .EX CHANGELOG_FLAG_FOLLOW CHANGELOG_FLAG_BLOCK CHANGELOG_FLAG_JOBID CHANGELOG_FLAG_EXTRA_FLAGS .EE .TP CHANGELOG_FLAG_FOLLOW Use changelog follow mode: .B llapi_changelog_recv() will not return when all records have been read. Instead it will block until a new record is available. It avoids restarting an instance and re-scan for newer changelogs. .TP CHANGELOG_FLAG_BLOCK Deprecated since Lustre 2.10. .TP CHANGELOG_FLAG_JOBID Pack jobid into the changelog records if available. .TP CHANGELOG_FLAG_EXTRA_FLAG Pack additional flag bits into the changelog record. .PP The function .B llapi_changelog_start_user() , similar to the function .B llapi_changelog_start() , initializes a new instance .I priv to read MDT changelogs, but with user-specific filtering, including username and mask. .P The .I username parameter specifies the changelog username or ID, e.g. "cl1", "cl1-user", "1", or "user". .P The .I mask parameter specifies the filtering mask in numeric form. If .I mask is 0, the user's registered .I MASK specified to .BR lctl-changelog_register (8) will be used. .PP The function .B llapi_changelog_set_xflags() specifies additional changelog flags with .I extra_flags mask for the instance .IR priv . To use those extra flags, CHANGELOG_FLAG_EXTRA_FLAG must be set by .B llapi_changelog_start() on .I flags parameter. .PP .B enum changelog_send_extra_flag values: .EX CHANGELOG_EXTRA_FLAG_UIDGID CHANGELOG_EXTRA_FLAG_NID CHANGELOG_EXTRA_FLAG_OMODE CHANGELOG_EXTRA_FLAG_XATTR .EE .TP CHANGELOG_EXTRA_FLAG_UIDGID Pack uid/gid into the changelog record .TP CHANGELOG_EXTRA_FLAG_NID Pack nid into the changelog record .TP CHANGELOG_EXTRA_FLAG_OMODE Pack open mode into the changelog record .TP CHANGELOG_EXTRA_FLAG_XATTR Pack xattr name into the changelog record .PP The function .B llapi_changelog_fini() closes the MDT's changelog char device and free internal pointers for the instance .IR priv . .SH RETURN VALUES .PP Return 0 on success or a negative errno value on failure. .SH ERRORS .TP 15 .SM -ENOMEM Insufficient memory to complete operation. .TP .SM -EINVAL One or more invalid arguments are given. .TP .SM -ENOENT MDT's changelog char device not found. Is the Lustre FS mounted? .TP .SM -EACCES Not enough permissions to open the changelog char device. By default, the device is only accessible to the root user. .SH EXAMPLE To register a user to watch file and directory creation and removal: .EX \& 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); .EE .SH AVAILABILITY .B llapi_changelog_start() and .B llapi_changelog_fini() are part of the .BR lustre (7) user application interface library since release 2.0.0, \# Added in commit 1.6.0-3165-g8901d15087b2 .B llapi_changelog_set_xflags() since release 2.11.0, \# Added in commit v2_10_55_0-122-g361edea47072 and .B llapi_changelog_start_user() since release 2.18.0. .SH SEE ALSO .BR lfs-changelog (1), .BR llapi_changelog_clear (3), .BR llapi_changelog_deregister (3), .BR llapi_changelog_get_fd (3), .BR llapi_changelog_in_buf (3), .BR llapi_changelog_recv (3), .BR llapi_changelog_register (3), .BR llapi_convert_str2mask (3), .BR lustreapi (7)