llapi_changelog_set_xflags(3)

LLAPI_CHANGELOG_START(3)

Lustre Library Functions

LLAPI_CHANGELOG_START(3)

NAME

llapi_changelog_start, llapi_changelog_start_user, llapi_changelog_set_xflags, llapi_changelog_fini - Initialize and clean a read instance for MDT changelogs

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);

The function llapi_changelog_start() initializes a new instance priv to read MDT changelogs. It opens the changelog char device corresponding to the MDT's name given by device (e.g: "lustrefs-MDT0000").

A changelog starting point can be specified with startrec record number. llapi_changelog_recv() will get changelog records with numbers greater or equal than startrec. 0 value means that all records will be read.

Some options can be passed to llapi_changelog_start() with flags mask.

enum changelog_send_flag values:

	CHANGELOG_FLAG_FOLLOW
	CHANGELOG_FLAG_BLOCK
	CHANGELOG_FLAG_JOBID
	CHANGELOG_FLAG_EXTRA_FLAGS

CHANGELOG_FLAG_FOLLOW: Use changelog follow mode: 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.
CHANGELOG_FLAG_BLOCK: Deprecated since Lustre 2.10.
CHANGELOG_FLAG_JOBID: Pack jobid into the changelog records if available.
CHANGELOG_FLAG_EXTRA_FLAG: Pack additional flag bits into the changelog record.

The function llapi_changelog_start_user() , similar to the function llapi_changelog_start() , initializes a new instance priv to read MDT changelogs, but with user-specific filtering, including username and mask.

The username parameter specifies the changelog username or ID, e.g. "cl1", "cl1-user", "1", or "user".

The mask parameter specifies the filtering mask in numeric form. If mask is 0, the user's registered MASK specified to lctl-changelog_register(8) will be used.

The function llapi_changelog_set_xflags() specifies additional changelog flags with extra_flags mask for the instance priv. To use those extra flags, CHANGELOG_FLAG_EXTRA_FLAG must be set by llapi_changelog_start() on flags parameter.

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: Pack uid/gid into the changelog record
CHANGELOG_EXTRA_FLAG_NID: Pack nid into the changelog record
CHANGELOG_EXTRA_FLAG_OMODE: Pack open mode into the changelog record
CHANGELOG_EXTRA_FLAG_XATTR: Pack xattr name into the changelog record

The function llapi_changelog_fini() closes the MDT's changelog char device and free internal pointers for the instance priv.

RETURN VALUES

Return 0 on success or a negative errno value on failure.

ERRORS

-ENOMEM: Insufficient memory to complete operation.
-EINVAL: One or more invalid arguments are given.
-ENOENT: MDT's changelog char device not found. Is the Lustre FS 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() are 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.