From: Etienne AUJAMES Date: Wed, 9 Nov 2022 16:11:31 +0000 (+0100) Subject: LU-12837 doc: add llapi_changelog* manpages X-Git-Tag: 2.15.53~49 X-Git-Url: https://git.whamcloud.com/gitweb?a=commitdiff_plain;h=refs%2Fchanges%2F84%2F49084%2F6;p=fs%2Flustre-release.git LU-12837 doc: add llapi_changelog* manpages This patch adds the following manpages for API changelog interface: - 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 This patch also cleans outdated comments about changelogs in Lustre API files. Signed-off-by: Etienne AUJAMES Test-Parameters: trivial Change-Id: Ie1481b820661e9e0ce9277ba4c65f51774f1e6bb Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/49084 Reviewed-by: Olaf Faaland Reviewed-by: Andreas Dilger Reviewed-by: Oleg Drokin Tested-by: jenkins Tested-by: Maloo --- diff --git a/lustre/doc/Makefile.am b/lustre/doc/Makefile.am index ba2a623..33e2b12 100644 --- a/lustre/doc/Makefile.am +++ b/lustre/doc/Makefile.am @@ -98,6 +98,14 @@ MANFILES = \ 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 \ @@ -189,6 +197,7 @@ LIBMAN = \ llapi_search_rootpath_by_dev.3 \ llapi_unlink_foreign.3 + SERVER_MANFILES = \ l_getidentity.8 \ l_getsepol.8 \ diff --git a/lustre/doc/llapi_changelog_clear.3 b/lustre/doc/llapi_changelog_clear.3 new file mode 100644 index 0000000..8ce44fa --- /dev/null +++ b/lustre/doc/llapi_changelog_clear.3 @@ -0,0 +1,58 @@ +.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 +.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) diff --git a/lustre/doc/llapi_changelog_fini.3 b/lustre/doc/llapi_changelog_fini.3 new file mode 100644 index 0000000..1496946 --- /dev/null +++ b/lustre/doc/llapi_changelog_fini.3 @@ -0,0 +1 @@ +.so man1/llapi_changelog_start.3 diff --git a/lustre/doc/llapi_changelog_free.3 b/lustre/doc/llapi_changelog_free.3 new file mode 100644 index 0000000..65753c4 --- /dev/null +++ b/lustre/doc/llapi_changelog_free.3 @@ -0,0 +1 @@ +.so man1/llapi_changelog_recv.3 diff --git a/lustre/doc/llapi_changelog_get_fd.3 b/lustre/doc/llapi_changelog_get_fd.3 new file mode 100644 index 0000000..a9396a1 --- /dev/null +++ b/lustre/doc/llapi_changelog_get_fd.3 @@ -0,0 +1,35 @@ +.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 +.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) diff --git a/lustre/doc/llapi_changelog_in_buf.3 b/lustre/doc/llapi_changelog_in_buf.3 new file mode 100644 index 0000000..6e8cf61 --- /dev/null +++ b/lustre/doc/llapi_changelog_in_buf.3 @@ -0,0 +1,31 @@ +.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 +.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) diff --git a/lustre/doc/llapi_changelog_recv.3 b/lustre/doc/llapi_changelog_recv.3 new file mode 100644 index 0000000..42b349e --- /dev/null +++ b/lustre/doc/llapi_changelog_recv.3 @@ -0,0 +1,65 @@ +.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 +.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) diff --git a/lustre/doc/llapi_changelog_set_xflags.3 b/lustre/doc/llapi_changelog_set_xflags.3 new file mode 100644 index 0000000..1496946 --- /dev/null +++ b/lustre/doc/llapi_changelog_set_xflags.3 @@ -0,0 +1 @@ +.so man1/llapi_changelog_start.3 diff --git a/lustre/doc/llapi_changelog_start.3 b/lustre/doc/llapi_changelog_start.3 new file mode 100644 index 0000000..dd4505c --- /dev/null +++ b/lustre/doc/llapi_changelog_start.3 @@ -0,0 +1,134 @@ +.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 +.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) diff --git a/lustre/doc/lustreapi.7 b/lustre/doc/lustreapi.7 index 0e776a8..5cbae56 100644 --- a/lustre/doc/lustreapi.7 +++ b/lustre/doc/lustreapi.7 @@ -11,6 +11,14 @@ settings specific to the Lustre filesystem (allocation policies, 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), diff --git a/lustre/include/uapi/linux/lustre/lustre_user.h b/lustre/include/uapi/linux/lustre/lustre_user.h index c4e00bf..676a33e 100644 --- a/lustre/include/uapi/linux/lustre/lustre_user.h +++ b/lustre/include/uapi/linux/lustre/lustre_user.h @@ -1748,11 +1748,11 @@ enum changelog_rec_extra_flags { }; 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, diff --git a/lustre/utils/liblustreapi_chlg.c b/lustre/utils/liblustreapi_chlg.c index ebb2450..9c14252 100644 --- a/lustre/utils/liblustreapi_chlg.c +++ b/lustre/utils/liblustreapi_chlg.c @@ -261,7 +261,7 @@ int llapi_changelog_recv(void *priv, struct changelog_rec **rech) 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) {