From 005da89eae3d3a9143806356aa69167e1e18630b Mon Sep 17 00:00:00 2001 From: Maximilian Dilger Date: Wed, 7 Aug 2024 03:34:02 -0600 Subject: [PATCH] LU-4315 doc: updating lfs-[h-l] man page style Updating files to match the new code style for Lustre manual pages as enforced by 'contrib/scripts/checkpatch-man.pl'. This also includes other changes like removing < > or { } for singular required arguments and placing [ ] around optional ones as well as making all arguments CAPITAL and italicized, literal arguments are bolded. Lines over 80 characters should be split at the natural line end rather than the word that goes over the limit as fewer lines will need to be modified when making changes if each sentence is on it's own line. Only using features that appear in groff 1.22.3 as this is the available version is CentOS 8. Checked files: - lfs-heat_get.1 - lfs-heat_set.1 - lfs-hsm.1 - lfs-hsm_action.1 - lfs-hsm_clear.1 - lfs-hsm_set.1 - lfs-hsm_state.1 - lfs-ladvise.1 Test-Parameters: trivial Signed-off-by: Frederick Dilger Change-Id: I58223c11b886fcc8abcf9aab37d72e36a5d98af3 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/56090 Tested-by: jenkins Tested-by: Maloo Reviewed-by: Andreas Dilger Reviewed-by: Arshad Hussain Reviewed-by: Oleg Drokin --- lustre/doc/lfs-heat_get.1 | 99 ++++++++++++++++++------------ lustre/doc/lfs-hsm.1 | 139 +++++++++++++++++++++++------------------ lustre/doc/lfs-ladvise.1 | 153 +++++++++++++++++++++++++++++++--------------- 3 files changed, 244 insertions(+), 147 deletions(-) diff --git a/lustre/doc/lfs-heat_get.1 b/lustre/doc/lfs-heat_get.1 index ff7faf2..13ccb6a 100644 --- a/lustre/doc/lfs-heat_get.1 +++ b/lustre/doc/lfs-heat_get.1 @@ -1,68 +1,89 @@ -.TH lfs-heat 1 "Feb. 09, 2019" Lustre "Lustre utility" +.TH LFS-HEAT 1 2024-08-30 Lustre "Lustre User Utilities" .SH NAME lfs-heat_get, lfs-heat_set \- commands used to interact with file heat features .SH SYNOPSIS -.B lfs heat_get|heat_set -.IR \fR<\fIFILE \fR...> -.br +.SY "lfs heat_get" +.IR FILE ... +.SY "lfs heat_set" +.RB [ --clear | -c ] +.RB [ --on | -O ] +.RB [ --off | -o ] +.YS .SH DESCRIPTION These are a set of lfs commands used to interact with Lustre file heat feature. Currently file heat is only stored in memory with file inode, it might be reset to be zero at any time with the release of the inode due to memory reclaim. -.TP -.B lfs heat_get \fR<\fIFILE \fR...> -Get file heat on file list. -.TP -.B lfs heat_set [\fB--clear\fR|\fB-c\fR] [\fB--off\fR|\fB-o\fR] [\fB--on\fR|\fB-O\fR] \fR<\fIFILE \fR...> -Set provided file heat flags on file list. +.B lfs heat_get +gets the file heat on the file list. +.B lfs heat_set +sets the provided file with heat flags on the file list. .SH OPTIONS .TP -.BR --clear | -c +.BR -c ", " --clear Clear file heat on given files. .TP -.BR --off | -o +.BR -c ", " --off Turn off file heat on given files. .TP -.BR --on | -O +.BR -O ", " --on Turn on file heat on given files. .SH EXAMPLES -.TP Turn on file heat support for the Lustre filesystem: -.B $ lctl set_param llite.$FSNAME*.file_heat=1 -.TP +.RS +.EX +.B # lctl set_param llite.$FSNAME*.file_heat=1 +.EE +.RE +.PP Turn off file heat support for the Lustre filesystem: -.B $ lctl set_param llite.$FSNAME*.file_heat=0 -.TP +.RS +.EX +.B # lctl set_param llite.$FSNAME*.file_heat=0 +.EE +.RE +.PP Display current file heat for foo: -.B $ lfs heat_get /mnt/lustre/foo -.br +.RS +.EX +.B # lfs heat_get /mnt/lustre/foo flags: 0 -.br +\& readsample: 0 -.br writesample: 16 -.br readbyte: 0 -.br writebyte: 16777216 -.br - -.TP +.EE +.RE +.PP Clear the file heat for foo: -.B $ lfs heat_set -c /mnt/lustre/foo -.TP +.RS +.EX +.B # lfs heat_set -c /mnt/lustre/foo +.EE +.RE +.PP Turn off file heat for foo: -.B $ lfs heat_set -o /mnt/lustre/foo -.TP +.RS +.EX +.B # lfs heat_set -o /mnt/lustre/foo +.EE +.RE +.PP Turn on file heat for foo: -.B $ lfs heat_set -O /mnt/lustre/foo -.SH AUTHOR +.RS +.EX +.B # lfs heat_set -O /mnt/lustre/foo +.EE +.RE +.SH AVAILABILITY The -.B lfs heat -command is part of the -.BR Lustre (7) -filesystem. - +.B lfs heat_get +and +.B lfs heat_set +commands are part of the +.BR lustre (7) +filesystem package since release 2.13.0 +.\" Added in commit v2_12_52-52-gae723cf816 .SH SEE ALSO -.BR lfs (1) +.BR lfs (1), .BR lustre (7) diff --git a/lustre/doc/lfs-hsm.1 b/lustre/doc/lfs-hsm.1 index b5261fd..d3a9aa6 100644 --- a/lustre/doc/lfs-hsm.1 +++ b/lustre/doc/lfs-hsm.1 @@ -1,90 +1,113 @@ -.TH LFS-HSM 1 "April 20, 2022" Lustre "Lustre/HSM binding utility" +.TH LFS-HSM 1 2024-08-30 Lustre "Lustre User Utilities" .SH NAME hsm_state, hsm_action, hsm_set, hsm_clear \- lfs commands used to interact with HSM features .SH SYNOPSIS -.B lfs hsm_state -[\fI\,FILE\/\fR]... -.PP -.B lfs hsm_action -[\fI\,FILE\/\fR]... -.PP -.B lfs hsm_set -[\fB\-\-norelease\fR] -[\fB\-\-noarchive\fR] -[\fB\-\-exists\fR] -[\fB\-\-archived\fR] -[\fB\-\-lost\fR] -[\fB\-\-archive-id\fR \fINUM\fR] -[\fI\,FILE\/\fR]... -.PP -.B lfs hsm_clear -[\fB\-\-norelease\fR] -[\fB\-\-noarchive\fR] -[\fB\-\-exists\fR] -[\fB\-\-archived\fR] -[\fB\-\-lost\fR] -[\fI\,FILE\/\fR]... -.PP +.SY "lfs hsm_state" +.RI [ FILE "] ..." +.SY "lfs hsm_action" +.RI [ FILE "] ..." +.SY "lfs hsm_set" +.RB [ --norelease ] +.RB [ --noarchive ] +.RB [ --exists ] +.RB [ --archived ] +.RB [ --lost ] +.RB [ --archive-id +.IR NUM ] +.RB [ FILE "] ..." +.SY "lfs hsm_clear" +.RB [ --norelease ] +.RB [ --noarchive ] +.RB [ --exists ] +.RB [ --archived ] +.RB [ --lost ] +.RB [ FILE "] ..." +.YS .SH DESCRIPTION These are a set of lfs commands used to interact with Lustre/HSM binding feature. .TP -.B lfs hsm_state \fR[\fI\,FILE\/\fR]... +.BR "lfs hsm_state " [ , \fIFILE / ]... Display the current HSM flags and archive ID for provided files. .TP -.B lfs hsm_action \fR[\fI\,FILE\/\fR]... +.BR "lfs hsm_action " [ , \fIFILE / ]... Display the in-progress HSM actions for provided files. .TP -.B lfs hsm_set \fR[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]... +.BR "lfs hsm_set " [ , \fIOPTION / "]... [" , \fIFILE / ]... Set provided HSM flags on file list. .TP -.B lfs hsm_clear \fR[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]... +.BR "lfs hsm_clear " [ , \fIOPTION / "]... [" , \fIFILE / ]... Clear the HSM related flags on file list. .PP Non-privileged user can only change the following flags: -.B norelease -, +.BR norelease , .B noarchive and -.B dirty. -.PP +.BR dirty . .SH OPTIONS .TP -.B \\--norelease -File should never be released. File data will stay in Lustre even if a copy exists in HSM backend. +.B --norelease +File should never be released. +File data will stay in Lustre even if a copy exists in HSM backend. .TP -.B \\--noarchive +.B --noarchive File should never be archived. Useful if this is a temporary file, for example. .TP -.B \\--dirty -File content is not in sync with HSM backend. File should be archived again. (root only) +.B --dirty +File content is not in sync with HSM backend. +File should be archived again. (root only) .TP -.B \\--exists +.B --exists A file copy exists in HSM backend. Useful mostly for debugging. (root only) .TP -.B \\--archived -An up-to-date file copy exists in HSM backend. Useful mostly for debugging. (root only) +.B --archived +An up-to-date file copy exists in HSM backend. +Useful mostly for debugging. (root only) .TP -.B \\--lost -File copy in HSM backend is not usable anymore and file could not be restored. It should be archived again. (root only) +.B --lost +File copy in HSM backend is not usable anymore and file could not be restored. +It should be archived again. (root only) .TP -.B \\--archive-id \fINUM\fR -Set archive number identifier to value \fINUM\fR. If archive-id is 0 or option is not provided, then default identifier 0 is used and means no identifier change. +.BI --archive-id " NUM" +Set archive number identifier to value +.IR NUM . +If archive-id is 0 or option is not provided, +then default identifier 0 is used and means no identifier change. .SH EXAMPLES -.TP -.B Display current HSM flag for foo: -$ lfs hsm_state /mnt/lustre/foo - +Display current HSM flag for foo: +.RS +.EX +.B # lfs hsm_state /mnt/lustre/foo /mnt/lustre/foo: (0x0000000b) exists dirty archived, archive_id: 1 - -.TP -.B Force a file to be considered as modified in lustre (dirty) -$ lfs hsm_set --dirty /mnt/lustre/motd - -.SH AUTHOR -Written by Aurelien Degremont. - -.SH KNOWN BUGS +.EE +.RE .PP -Please report all bugs to https://jira.whamcloud.com/ +Force a file to be considered as modified in lustre (dirty): +.RS +.EX +.B # lfs hsm_set --dirty /mnt/lustre/motd +.EE +.RE +.SH AUTHORS +Written by Aurelien Degremont. +.SH AVAILABILITY +.BR "lfs hsm_action" , +.BR "lfs hsm_clear" , +.B lfs hsm_set +and +.B lfs hsm_state +are part of the +.BR lustre (7) +filesystem package. +.B lfs hsm_action +was added in release 1.7.0. +.\" Added in commit 1.6.1-2914-g4c1c3b4d33 +.B lfs hsm_clear +was added in release 2.4.0. +.\" Added in commit v2_3_60-5-gc42b426c87 +.B lfs hsm_set +and +.B lfs hsm_state +were added in release 2.0.0. +.\" Added in commit v2_0_0-rc1a-339-g2e0ad6d400 .SH SEE ALSO .BR lfs (1) diff --git a/lustre/doc/lfs-ladvise.1 b/lustre/doc/lfs-ladvise.1 index 933fe13..1a6b63e 100644 --- a/lustre/doc/lfs-ladvise.1 +++ b/lustre/doc/lfs-ladvise.1 @@ -1,14 +1,27 @@ -.TH LFS-LADVISE 1 2015-11-30 "Lustre" "Lustre Utilities" +.TH LFS-LADVISE 1 2024-08-30 Lustre "Lustre User Utilities" .SH NAME lfs-ladvise \- give file access advices or hints to server. .SH SYNOPSIS -.br -.B lfs ladvise [--advice|-a ADVICE ] [--background|-b] - \fB[--start|-s START[kMGT]] - \fB{[--end|-e END[kMGT]] | [--length|-l LENGTH[kMGT]]} - \fB{[--mode|-m MODE] | [--unset|-u]} - \fB ...\fR -.br +.SY "lfs ladvise" +.RB [ --advice | -a +.IR ADVICE ] +.RB [ --background | -b ] +.RB [ --start | -s +.I START\c +.RB [ kMGT ]] +.RB {[ --end | -e +.I END\c +.RB [ kMGT ]] +| +.RB [ --length | -l +.I LENGTH\c +.RB [ kMGT ]]} +.RB {[ --mode | -m +.IR MODE ] +| +.RB [ --unset | -u ]} +.IR FILE " ..." +.YS .SH DESCRIPTION Give file access advices or hints to Lustre server side, usually OSS. This lfs command is similar to the Linux @@ -18,40 +31,50 @@ system call and except it can forward the hints from Lustre clients to remote servers. .SH OPTIONS .TP -\fB\-a\fR, \fB\-\-advice\fR=\fIADVICE\fR -Give advice or hint of type \fIADVICE\fR. Advice types are: -.RS 1.2i +.BR -a ", " --advice= \fIADVICE +Give advice or hint of type +.I ADVICE +Advice types are: +.TP 15 +.B willread +to prefetch data into server cache .TP -\fBwillread\fR to prefetch data into server cache +.B dontneed +to cleanup data cache on server .TP -\fBdontneed\fR to cleanup data cache on server +.B lockahead +to request a lock on a specified extent of a file .TP -\fBlockahead\fR to request a lock on a specified extent of a file -\fBlocknoexpand\fR to disable server side lock expansion for a file -.RE -.TP -\fB\-b\fR, \fB\-\-background +.B locknoexpand +to disable server side lock expansion for a file +.TP 7 +.BR -b ", " --background Enable the advices to be sent and handled asynchronously. .TP -\fB\-s\fR, \fB\-\-start\fR=\fISTART_OFFSET\fR -File range starts from \fISTART_OFFSET\fR. +.BR -s ", " --start= \fISTART_OFFSET +File range starts from +.I START_OFFSET. .TP -\fB\-e\fR, \fB\-\-end\fR=\fIEND_OFFSET\fR -File range ends at (not including) \fIEND_OFFSET\fR. +.BR -e ", " --end= END_OFFSET +File range ends at (not including) +.I END_OFFSET. This option may not be specified at the same time as the -l option. .TP -\fB\-l\fR, \fB\-\-length\fR=\fILENGTH\fR -File range has length of \fILENGTH\fR. This option may not be specified at the +.BR -l ", " --length= LENGTH +File range has length of +.I LENGTH. +This option may not be specified at the same time as the -e option. .TP -\fB\-m\fR, \fB\-\-mode\fR=\fIMODE\fR -Specify the lock \fIMODE\fR. This option is only valid with lockahead +.BR -m ", " --mode= MODE +Specify the lock +.I MODE. +This option is only valid with lockahead advice. Valid modes are: READ, WRITE .TP -\fB\-u\fR, \fB\-\-unset\fR=\fIUNSET\fR +.BR -u ", " --unset= UNSET Unset the previous advice. Currently only valid with locknoexpand advice. -.SH NOTE -.PP +.SH NOTES Typically, .B lfs ladvise forwards the advice to Lustre servers without @@ -59,38 +82,68 @@ guaranteeing how and when servers will react to the advice. Actions may or may not be triggered when the advices are received, depending on the type of the advice, whether the backing filesystem type supports that advice, as well as the real-time decision of the affected server-side components. - +.PP A typical usage of ladvise is to enable applications and users with external knowledge to intervene in server-side cache management. For example, if a group of different clients are doing small random reads of a file, prefetching pages into OSS cache with big linear reads before the random IO is a net benefit. Fetching that data into each client cache with fadvise() may not be a benefit if any individual client only reads a subset of the file. - +.PP The main difference between Linux fadvise() system call and ladvise is that fadvise() is only a client side mechanism that does not pass the advice to the filesystem, while ladvise can send advices or hints to Lustre server sides. - .SH EXAMPLES -.TP -.B $ lfs ladvise -a willread -s 0 -e 1024M /mnt/lustre/file1 -This gives the OST(s) holding the first 1GB of \fB/mnt/lustre/file1\fR a hint -that the first 1GB of that file will be read soon. -.TP -.B $ lfs ladvise -a dontneed -s 0 -e 1G /mnt/lustre/file1 -This gives the OST(s) holding the first 1GB of \fB/mnt/lustre/file1\fR a hint -that the first 1GB of file will not be read in the near future, thus the OST(s) -could clear the cache of that file in the memory. -.B $ lfs ladvise -a lockahead -s 0 -e 1048576 -m READ /mnt/lustre/file1 -Request a read lock on the first 1 MiB of /mnt/lustre/file1. -.B $ $ lfs ladvise -a lockahead -s 0 -e 4096 -m WRITE ./file1 -Request a write lock on the first 4KiB of /mnt/lustre/file1. -.B $ $ lfs ladvise -a locknoexpand ./file1 -Set disable lock expansion on ./file1 -.B $ $ lfs ladvise -a locknoexpand -u ./file1 -Unset disable lock expansion on ./file1 +Gives the OST(s) holding the first 1GB of +.B mnt/lustre/file1 +a hint that the first 1GB of that file will be read soon: +.RS +.EX +.B # lfs ladvise -a willread -s 0 -e 1024M /mnt/lustre/file1 +.EE +.RE +.PP +Gives the OST(s) holding the first 1GB of +.B /mnt/lustre/file1 +a hint that the first 1GB of file will not be read in the near future, +thus the OST(s) could clear the cache of that file in the memory: +.RS +.EX +.B # lfs ladvise -a dontneed -s 0 -e 1G /mnt/lustre/file1 +.EE +.RE +.PP +Request a read lock on the first 1 MiB of /mnt/lustre/file1: +.RS +.EX +.B # lfs ladvise -a lockahead -s 0 -e 1048576 -m READ /mnt/lustre/file1 +.EE +.RE +Request a write lock on the first 4KiB of /mnt/lustre/file1: +.RS +.EX +.B # lfs ladvise -a lockahead -s 0 -e 4096 -m WRITE ./file1 +.EE +.RE +Set disable lock expansion on ./file1: +.RS +.EX +.B # lfs ladvise -a locknoexpand ./file1 +.EE +.RE +Unset disable lock expansion on ./file1: +.RS +.EX +.B # lfs ladvise -a locknoexpand -u ./file1 +.EE +.RE .SH AVAILABILITY -The lfs ladvise command is part of the Lustre filesystem. +The +.B lfs ladvise +command is part of the +.BR lustre (7) +filesystem package since release 2.9.0 +.\" Added in commit v2_8_51-30-ge14246641c .SH SEE ALSO .BR lfs (1), .BR fadvise64 (2), -- 1.8.3.1