* [PATCH] swapon.2: Document NOSWAP and additional DISCARD flags @ 2021-07-22 21:21 Evan Green 2021-07-23 17:41 ` Evan Green 2021-07-25 20:50 ` Alejandro Colomar (man-pages) 0 siblings, 2 replies; 4+ messages in thread From: Evan Green @ 2021-07-22 21:21 UTC (permalink / raw) To: linux-man; +Cc: Andrew Morton, Evan Green Fix the FIXME and finally document SWAP_FLAG_DISCARD_ONCE and SWAP_FLAG_DISCARD_PAGES from Linux 3.11. Additionally, document SWAP_FLAG_NOSWAP, a shiny new flag being introduced in Linux 5.14. See the following link: https://lore.kernel.org/lkml/20210721143946.v3.1.I09866d90c6de14f21223a03e9e6a31f8a02ecbaf@changeid/ Signed-off-by: Evan Green <evgreen@chromium.org> --- man2/swapon.2 | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/man2/swapon.2 b/man2/swapon.2 index 07d5fe86c..d568da993 100644 --- a/man2/swapon.2 +++ b/man2/swapon.2 @@ -33,13 +33,10 @@ .\" 2004-12-14 mtk, Anand Kumria: added new errors .\" 2007-06-22 Ivana Varekova <varekova@redhat.com>, mtk .\" Update text describing limit on number of swap files. +.\" 2021-07-22 Evan Green <evgreen@chromium.org> +.\" Document _DISCARD_ONCE, _DISCARD_PAGES, and _NOSWAP flags. .\" -.\" FIXME Linux 3.11 added SWAP_FLAG_DISCARD_ONCE and SWAP_FLAG_DISCARD_PAGES -.\" commit dcf6b7ddd7df8965727746f89c59229b23180e5a -.\" Author: Rafael Aquini <aquini@redhat.com> -.\" Date: Wed Jul 3 15:02:46 2013 -0700 -.\" -.TH SWAPON 2 2021-03-22 "Linux" "Linux Programmer's Manual" +.TH SWAPON 2 2021-07-22 "Linux" "Linux Programmer's Manual" .SH NAME swapon, swapoff \- start/stop swapping to file/device .SH SYNOPSIS @@ -81,9 +78,23 @@ flag is specified in the argument, freed swap pages will be discarded before they are reused, if the swap device supports the discard or trim operation. (This may improve performance on some Solid State Devices, -but often it does not.) +but often it does not.) In conjunction with this flag, callers may add +.B SWAP_FLAG_DISCARD_ONCE +to perform a single discard over the entire region at swapon time, and/or +.B SWAP_FLAG_DISCARD_PAGES +to perform discards as swap pages are freed. If neither is specified, +both are assumed. See also NOTES. .PP +If the +.B SWAP_FLAG_NOSWAP +flag is specified in the +.BR swapon () +.I swapflags +argument, then the added swap region will not be eligible for regular +swap activities. It can still be used for hibernate, enabling callers +to steer the swap and hibernate regions independently. +.PP These functions may be used only by a privileged process (one having the .B CAP_SYS_ADMIN capability). @@ -201,6 +212,14 @@ which still discards the entire swap area when .BR swapon () is called, even if that flag bit is not set. +.PP +.B SWAP_FLAG_DISCARD_ONCE +and +.B SWAP_FLAG_DISCARD_PAGES +were introduced in Linux 3.11. +.PP +.B SWAP_FLAG_NOSWAP +was introduced in Linux 5.14. .SH SEE ALSO .BR mkswap (8), .BR swapoff (8), -- 2.31.0 ^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH] swapon.2: Document NOSWAP and additional DISCARD flags 2021-07-22 21:21 [PATCH] swapon.2: Document NOSWAP and additional DISCARD flags Evan Green @ 2021-07-23 17:41 ` Evan Green 2021-07-25 20:50 ` Alejandro Colomar (man-pages) 1 sibling, 0 replies; 4+ messages in thread From: Evan Green @ 2021-07-23 17:41 UTC (permalink / raw) To: linux-man; +Cc: Andrew Morton On Thu, Jul 22, 2021 at 2:21 PM Evan Green <evgreen@chromium.org> wrote: > > Fix the FIXME and finally document SWAP_FLAG_DISCARD_ONCE and > SWAP_FLAG_DISCARD_PAGES from Linux 3.11. Additionally, document > SWAP_FLAG_NOSWAP, a shiny new flag being introduced in Linux 5.14. See > the following link: > > https://lore.kernel.org/lkml/20210721143946.v3.1.I09866d90c6de14f21223a03e9e6a31f8a02ecbaf@changeid/ > > Signed-off-by: Evan Green <evgreen@chromium.org> Please disregard, the patch introducing the NOSWAP flag is still in flux. -Evan ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] swapon.2: Document NOSWAP and additional DISCARD flags 2021-07-22 21:21 [PATCH] swapon.2: Document NOSWAP and additional DISCARD flags Evan Green 2021-07-23 17:41 ` Evan Green @ 2021-07-25 20:50 ` Alejandro Colomar (man-pages) 2021-07-26 16:23 ` Evan Green 1 sibling, 1 reply; 4+ messages in thread From: Alejandro Colomar (man-pages) @ 2021-07-25 20:50 UTC (permalink / raw) To: Evan Green; +Cc: Andrew Morton, linux-man Hi Evan, On 7/22/21 11:21 PM, Evan Green wrote: > Fix the FIXME and finally document SWAP_FLAG_DISCARD_ONCE and > SWAP_FLAG_DISCARD_PAGES from Linux 3.11. Additionally, document > SWAP_FLAG_NOSWAP, a shiny new flag being introduced in Linux 5.14. See > the following link: > > https://lore.kernel.org/lkml/20210721143946.v3.1.I09866d90c6de14f21223a03e9e6a31f8a02ecbaf@changeid/ > > Signed-off-by: Evan Green <evgreen@chromium.org> Discarded as requested :) However, please see a few comments below. Thanks, Alex > --- > man2/swapon.2 | 33 ++++++++++++++++++++++++++------- > 1 file changed, 26 insertions(+), 7 deletions(-) > > diff --git a/man2/swapon.2 b/man2/swapon.2 > index 07d5fe86c..d568da993 100644 > --- a/man2/swapon.2 > +++ b/man2/swapon.2 > @@ -33,13 +33,10 @@ > .\" 2004-12-14 mtk, Anand Kumria: added new errors > .\" 2007-06-22 Ivana Varekova <varekova@redhat.com>, mtk > .\" Update text describing limit on number of swap files. > +.\" 2021-07-22 Evan Green <evgreen@chromium.org> > +.\" Document _DISCARD_ONCE, _DISCARD_PAGES, and _NOSWAP flags. > .\" > -.\" FIXME Linux 3.11 added SWAP_FLAG_DISCARD_ONCE and SWAP_FLAG_DISCARD_PAGES > -.\" commit dcf6b7ddd7df8965727746f89c59229b23180e5a > -.\" Author: Rafael Aquini <aquini@redhat.com> > -.\" Date: Wed Jul 3 15:02:46 2013 -0700 > -.\" > -.TH SWAPON 2 2021-03-22 "Linux" "Linux Programmer's Manual" > +.TH SWAPON 2 2021-07-22 "Linux" "Linux Programmer's Manual" The .TH line is updated with a script, so we don't touch it manually. > .SH NAME > swapon, swapoff \- start/stop swapping to file/device > .SH SYNOPSIS > @@ -81,9 +78,23 @@ flag is specified in the > argument, freed swap pages will be discarded before they are reused, > if the swap device supports the discard or trim operation. > (This may improve performance on some Solid State Devices, > -but often it does not.) > +but often it does not.) In conjunction with this flag, callers may add See the following extract from man-pages(7): $ man 7 man-pages | sed -n '/Use semantic newlines/,/^$/p'; Use semantic newlines In the source of a manual page, new sentences should be started on new lines, and long sentences should split into lines at clause breaks (commas, semicolons, colons, and so on). This convention, sometimes known as "semantic new‐ lines", makes it easier to see the effect of patches, which often operate at the level of individual sentences or sen‐ tence clauses. > +.B SWAP_FLAG_DISCARD_ONCE > +to perform a single discard over the entire region at swapon time, and/or > +.B SWAP_FLAG_DISCARD_PAGES > +to perform discards as swap pages are freed. If neither is specified, > +both are assumed. > See also NOTES. > .PP > +If the > +.B SWAP_FLAG_NOSWAP > +flag is specified in the > +.BR swapon () > +.I swapflags > +argument, then the added swap region will not be eligible for regular > +swap activities. It can still be used for hibernate, enabling callers > +to steer the swap and hibernate regions independently. > +.PP > These functions may be used only by a privileged process (one having the > .B CAP_SYS_ADMIN > capability). > @@ -201,6 +212,14 @@ which still discards the > entire swap area when > .BR swapon () > is called, even if that flag bit is not set. > +.PP > +.B SWAP_FLAG_DISCARD_ONCE > +and > +.B SWAP_FLAG_DISCARD_PAGES > +were introduced in Linux 3.11. > +.PP > +.B SWAP_FLAG_NOSWAP > +was introduced in Linux 5.14. > .SH SEE ALSO > .BR mkswap (8), > .BR swapoff (8), > -- Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/ ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] swapon.2: Document NOSWAP and additional DISCARD flags 2021-07-25 20:50 ` Alejandro Colomar (man-pages) @ 2021-07-26 16:23 ` Evan Green 0 siblings, 0 replies; 4+ messages in thread From: Evan Green @ 2021-07-26 16:23 UTC (permalink / raw) To: Alejandro Colomar (man-pages); +Cc: Andrew Morton, linux-man On Sun, Jul 25, 2021 at 1:50 PM Alejandro Colomar (man-pages) <alx.manpages@gmail.com> wrote: > > Hi Evan, > > On 7/22/21 11:21 PM, Evan Green wrote: > > Fix the FIXME and finally document SWAP_FLAG_DISCARD_ONCE and > > SWAP_FLAG_DISCARD_PAGES from Linux 3.11. Additionally, document > > SWAP_FLAG_NOSWAP, a shiny new flag being introduced in Linux 5.14. See > > the following link: > > > > https://lore.kernel.org/lkml/20210721143946.v3.1.I09866d90c6de14f21223a03e9e6a31f8a02ecbaf@changeid/ > > > > Signed-off-by: Evan Green <evgreen@chromium.org> > > Discarded as requested :) > > However, please see a few comments below. > > Thanks, > > Alex > > > --- > > man2/swapon.2 | 33 ++++++++++++++++++++++++++------- > > 1 file changed, 26 insertions(+), 7 deletions(-) > > > > diff --git a/man2/swapon.2 b/man2/swapon.2 > > index 07d5fe86c..d568da993 100644 > > --- a/man2/swapon.2 > > +++ b/man2/swapon.2 > > @@ -33,13 +33,10 @@ > > .\" 2004-12-14 mtk, Anand Kumria: added new errors > > .\" 2007-06-22 Ivana Varekova <varekova@redhat.com>, mtk > > .\" Update text describing limit on number of swap files. > > +.\" 2021-07-22 Evan Green <evgreen@chromium.org> > > +.\" Document _DISCARD_ONCE, _DISCARD_PAGES, and _NOSWAP flags. > > .\" > > -.\" FIXME Linux 3.11 added SWAP_FLAG_DISCARD_ONCE and SWAP_FLAG_DISCARD_PAGES > > -.\" commit dcf6b7ddd7df8965727746f89c59229b23180e5a > > -.\" Author: Rafael Aquini <aquini@redhat.com> > > -.\" Date: Wed Jul 3 15:02:46 2013 -0700 > > -.\" > > -.TH SWAPON 2 2021-03-22 "Linux" "Linux Programmer's Manual" > > +.TH SWAPON 2 2021-07-22 "Linux" "Linux Programmer's Manual" > > The .TH line is updated with a script, so we don't touch it manually. Ack. > > > .SH NAME > > swapon, swapoff \- start/stop swapping to file/device > > .SH SYNOPSIS > > @@ -81,9 +78,23 @@ flag is specified in the > > argument, freed swap pages will be discarded before they are reused, > > if the swap device supports the discard or trim operation. > > (This may improve performance on some Solid State Devices, > > -but often it does not.) > > +but often it does not.) In conjunction with this flag, callers may add > > > See the following extract from man-pages(7): > > $ man 7 man-pages | sed -n '/Use semantic newlines/,/^$/p'; > Use semantic newlines > In the source of a manual page, new sentences should be > started on new lines, and long sentences should split into > lines at clause breaks (commas, semicolons, colons, and so > on). This convention, sometimes known as "semantic new‐ > lines", makes it easier to see the effect of patches, which > often operate at the level of individual sentences or sen‐ > tence clauses. > Gotcha, thanks for the gentle education. I'll hopefully have a revised version of this patch out at some point once the main change is stabilized. I'll be sure to fix these issues, if you notice anything else in this patch that would need to be corrected I can include that in the next spin too. -Evan ^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2021-07-26 16:24 UTC | newest] Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2021-07-22 21:21 [PATCH] swapon.2: Document NOSWAP and additional DISCARD flags Evan Green 2021-07-23 17:41 ` Evan Green 2021-07-25 20:50 ` Alejandro Colomar (man-pages) 2021-07-26 16:23 ` Evan Green
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).