Re: [PATCH] swapon.2: Document NOSWAP and additional DISCARD flags

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxxxxx>

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@xxxxxxxxxx>, mtk
  .\"     Update text describing limit on number of swap files.
+.\" 2021-07-22 Evan Green <evgreen@xxxxxxxxxxxx>
+.\"     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@xxxxxxxxxx>
-.\"	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/



[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux