LIBMAN = \
lustreapi.7 \
+ llapi_changelog_clear.3 \
+ llapi_changelog_fini.3 \
+ llapi_changelog_free.3 \
+ llapi_changelog_get_fd.3 \
+ llapi_changelog_in_buf.3 \
+ llapi_changelog_recv.3 \
+ llapi_changelog_set_xflags.3 \
+ llapi_changelog_start.3 \
llapi_create_volatile_param.3 \
llapi_fd2parent.3 \
llapi_fid_parse.3 \
llapi_search_rootpath_by_dev.3 \
llapi_unlink_foreign.3
+
SERVER_MANFILES = \
l_getidentity.8 \
l_getsepol.8 \
--- /dev/null
+.TH llapi_changelog_clear 3 "2022-11-08" "" "Lustre User API"
+.SH NAME
+llapi_changelog_clear \- Clear changelog records for a changelog consumer
+.SH SYNOPSIS
+.nf
+.B #include <lustre/lustreapi.h>
+.PP
+.BI "int llapi_changelog_clear(const char *" mdtname ", const char *" idstr ",
+.BI " long long " endrec ");"
+.fi
+.SH DESCRIPTION
+.PP
+The function
+.B llapi_changelog_clear()
+indicates that changelog records previous to
+.I endrec
+are no longer of interest to a particular consumer
+.I idstr
+, potentially allowing the MDT
+.I mdtname
+(e.g: "lustrefs-MDT0000") to free up disk space.
+.PP
+An
+.I endrec
+of 0 indicates the current last record.
+.PP
+Changelog consumers must be registered on the
+MDT node using:
+.br
+.BI "lctl --device " MDT_NAME " changelog_register"
+.SH RETURN VALUES
+.PP
+Return the file descriptor on success or a negative errno value on failure.
+.SH ERRORS
+.TP 15
+.SM -EINVAL
+One or more invalid arguments are given.
+.TP
+.SM -ENOENT
+MDT's changelog char device or changelog user not found.
+.TP
+.SM -ENOPERM
+Not enough permissions to open the changelog char device. By default, the device
+is only accessible to the root user.
+.SH EXAMPLE
+An example can be found for in lfs.c source file.
+.B lfs_changelog_clear
+implements the following command:
+.br
+.BI "lfs changelog_clear " MDTNAME " " ID " " ENDREC ""
+.SH "SEE ALSO"
+.BR lfs-changelog_clear (1),
+.BR llapi_changelog_get_fd (3)
+.BR llapi_changelog_in_buf (3),
+.BR llapi_changelog_recv (3),
+.BR llapi_changelog_start (3),
+.BR lustreapi (7),
+.BR lctl-changelog_register (8)
--- /dev/null
+.so man1/llapi_changelog_start.3
--- /dev/null
+.so man1/llapi_changelog_recv.3
--- /dev/null
+.TH llapi_changelog_get_fd 3 "2022-11-08" "" "Lustre User API"
+.SH NAME
+llapi_changelog_get_fd \- Return the file descriptor of the changelog device
+.SH SYNOPSIS
+.nf
+.B #include <lustre/lustreapi.h>
+.PP
+.BI "int llapi_changelog_get_fd(void *" priv ");"
+.fi
+.SH DESCRIPTION
+.PP
+The function
+.B llapi_changelog_get_fd()
+return the file descriptor of changelog char device for the instance
+.IR priv .
+.PP
+This can be used to call
+.B poll()
+on the file descriptor to get events on the
+changelog device.
+.SH RETURN VALUES
+.PP
+Return the file descriptor on success or a negative errno value on failure.
+.SH ERRORS
+.TP 15
+.SM -EINVAL
+.I priv
+argument is invalid.
+.SH "SEE ALSO"
+.BR poll (2),
+.BR llapi_changelog_clear (3)
+.BR llapi_changelog_in_buf (3),
+.BR llapi_changelog_recv (3),
+.BR llapi_changelog_start (3),
+.BR lustreapi (7)
--- /dev/null
+.TH llapi_changelog_in_buf 3 "2022-11-08" "" "Lustre User API"
+.SH NAME
+llapi_changelog_in_buf \- Check if there is changelog records in the internal buffer
+.SH SYNOPSIS
+.nf
+.B #include <lustre/lustreapi.h>
+.PP
+.BI "int llapi_changelog_in_buf(void *" priv ");"
+.fi
+.SH DESCRIPTION
+.PP
+The function
+.B llapi_changelog_in_buf()
+checks if there are still changelog records in the read buffer for the
+.I priv
+instance.
+.PP
+.B llapi_changelog_in_buf()
+with
+.B llapi_changelog_recv()
+can be used to dequeue all the changelog records still in the read buffer.
+.SH RETURN VALUES
+.PP
+Return 1 if changelogs records are present in the internal read buffer,
+otherwise return 0.
+.SH "SEE ALSO"
+.BR llapi_changelog_clear (3)
+.BR llapi_changelog_get_fd (3),
+.BR llapi_changelog_recv (3),
+.BR llapi_changelog_start (3),
+.BR lustreapi (7)
--- /dev/null
+.TH llapi_changelog_recv 3 "2022-11-08" "" "Lustre User API"
+.SH NAME
+llapi_changelog_recv, llapi_changelog_free \- Read and free a changelog records
+.SH SYNOPSIS
+.nf
+.B #include <lustre/lustreapi.h>
+.PP
+.BI "int llapi_changelog_recv(void *" priv ", struct changelog_rec **" rech ");"
+.PP
+.BI "int llapi_changelog_free(struct changelog_rec **" rech ");"
+.fi
+.SH DESCRIPTION
+.PP
+The function
+.B llapi_changelog_recv()
+allocates and reads the next changelog record
+.I rech
+from the changelog reader instance
+.IR priv .
+.PP
+The function
+.B llapi_changelog_free()
+releases the allocated record
+.IR rech .
+.SH NOTES
+If
+.B llapi_changelog_start()
+initializes
+.I priv
+with CHANGELOG_FLAG_FOLLOW flag,
+.B llapi_changelog_recv()
+can block waiting for new records.
+.SH RETURN VALUES
+.TP 15
+.SM 0
+On success
+.TP
+.SM 1
+End of records
+.TP
+.SM -errno
+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 -EIO
+Failed to read the changelog record on the MDT.
+.SH EXAMPLE
+An example can be found for in lfs.c source file.
+.B lfs_changelog()
+implements the following command:
+.br
+.BI "lfs changelog [--follow] " MDTNAME " [" STARTREC " [" ENDREC "]]"
+.SH "SEE ALSO"
+.BR lfs-changelog (1),
+.BR llapi_changelog_clear (3),
+.BR llapi_changelog_get_fd (3),
+.BR llapi_changelog_in_buf (3),
+.BR llapi_changelog_start (3),
+.BR lustreapi (7)
--- /dev/null
+.so man1/llapi_changelog_start.3
--- /dev/null
+.TH llapi_changelog_start 3 "2022-11-08" "" "Lustre User API"
+.SH NAME
+llapi_changelog_start, llapi_changelog_set_xflags, llapi_changelog_fini \- Initialize and clean a read instance for MDT changelogs
+.SH SYNOPSIS
+.nf
+.B #include <lustre/lustreapi.h>
+.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_set_xflags(void *" priv,
+.BI " enum changelog_send_extra_flag " extra_flags ");"
+.PP
+.BI "int llapi_changelog_fini(void **" priv ");"
+.fi
+.SH DESCRIPTION
+.PP
+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").
+.br
+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:
+.nf
+.LP
+ CHANGELOG_FLAG_FOLLOW
+ CHANGELOG_FLAG_BLOCK
+ CHANGELOG_FLAG_JOBID
+ CHANGELOG_FLAG_EXTRA_FLAGS
+.fi
+.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_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:
+.nf
+.LP
+ CHANGELOG_EXTRA_FLAG_UIDGID
+ CHANGELOG_EXTRA_FLAG_NID
+ CHANGELOG_EXTRA_FLAG_OMODE
+ CHANGELOG_EXTRA_FLAG_XATTR
+.fi
+.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
+An example can be found for in lfs.c source file.
+.B lfs_changelog()
+implements the following command:
+.br
+.BI "lfs changelog [--follow] " MDTNAME " [" STARTREC " [" ENDREC "]]"
+.SH "SEE ALSO"
+.BR lfs-changelog (1),
+.BR llapi_changelog_clear (3)
+.BR llapi_changelog_get_fd (3),
+.BR llapi_changelog_in_buf (3),
+.BR llapi_changelog_recv (3),
+.BR lustreapi (7)
quotas, file layouts, etc). See the referenced man pages for details.
.SH SEE ALSO
.sp
+.BR llapi_changelog_clear (3)
+.BR llapi_changelog_fini (3)
+.BR llapi_changelog_free (3)
+.BR llapi_changelog_get_fd (3)
+.BR llapi_changelog_in_buf (3)
+.BR llapi_changelog_recv (3)
+.BR llapi_changelog_set_xflags (3)
+.BR llapi_changelog_start (3)
.BR llapi_create_volatile_param (3),
.BR llapi_fd2parent (3),
.BR llapi_fid2path (3),
};
enum changelog_send_flag {
- /* Not yet implemented */
+ /* Use changelog follow mode: llapi_changelog_recv() will not stop at
+ * the end of records and wait for new records to be generated.
+ */
CHANGELOG_FLAG_FOLLOW = 0x01,
- /* Blocking IO makes sense in case of slow user parsing of the records,
- * but it also prevents us from cleaning up if the records are not
- * consumed. */
+ /* Deprecated since Lustre 2.10 */
CHANGELOG_FLAG_BLOCK = 0x02,
/* Pack jobid into the changelog records if available. */
CHANGELOG_FLAG_JOBID = 0x04,
refresh = chlg_read_bulk(cp);
if (refresh == 0) {
- /* EOF, CHANGELOG_FLAG_FOLLOW ignored for now LU-7659 */
+ /* EOF */
rc = 1;
goto out_free;
} else if (refresh < 0) {
git://git.whamcloud.com / fs / lustre-release.git / commitdiff