Skip to contentSkip to conversation

man/man2/swapon2: describe SWAP_FLAG_DISCARD_{ONCE,PAGES}

PATCH In review Mingye Wang 2 participants 2 messages Nov 9, 2025 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 man/man2/swapon2: describe SWAP_FLAG_DISCARD_{ONCE,PAGES}

There has been a TODO to describe these two new flags for a long time now. This commit finishes it.

---
 man/man2/swapon.2 | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
man/man2/swapon.2 +26 -0
index df5e8d8..1d2db47 100644
@@ -53,6 +53,32 @@ 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.)
+.P
+(Linux 3.11+) If either of the
+.B SWAP_FLAG_DISCARD_ONCE
+or
+.B SWAP_FLAG_DISCARD_PAGES
+flags are specified in the
+.BR swapon ()
+.I swapflags
+along with
+.BR SWAP_FLAG_DISCARD ,
+the discard of swap pages is controlled as follows:
+.RS 4n
+.IP SWAP_FLAG_DISCARD_ONCE 4n
+\- Discard only occurs when the swap area is first enabled
+with
+.BR swapon () .
+Minimum overhead is incurred for subsequent swap page frees.
+.IP SWAP_FLAG_DISCARD_PAGES 4n
+\- Discard occurs on every swap page free, asynchronously.
+This may incur significant overhead.
+.RE
+.P
+Setting both flags results in the behavior of
+.BR SWAP_FLAG_DISCARD_ONCE .
+Setting neither results in both types of discard being performed.
+.P
 See also NOTES.
 .P
 These functions may be used only by a privileged process (one having the
Signature · 1 line
2.51.0
#1 lore raw

Hi Mingye,

Quoted 2 lines · Mingye Wang

There has been a TODO to describe these two new flags for a long time now. This commit finishes it.

This commit should remove the TODO, right?

Quoted 9 lines
---
 man/man2/swapon.2 | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
man/man2/swapon.2 +0 -0
index df5e8d8..1d2db47 100644

man/man2/swapon.2 argument, freed swap pages will be discarded before they are reused, · line 57

Quoted 5 lines
man/man2/swapon.2 +2 -0
@@ -53,6 +53,32 @@ 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.)
+.P
+(Linux 3.11+) If either of the

Please use "Since Linux 3.11,", for consistency with other pages.

man/man2/swapon.2 argument, freed swap pages will be discarded before they are reused, · line 68

Quoted 11 lines
man/man2/swapon.2 +11 -0
+.B SWAP_FLAG_DISCARD_ONCE
+or
+.B SWAP_FLAG_DISCARD_PAGES
+flags are specified in the
+.BR swapon ()
+.I swapflags
+along with
+.BR SWAP_FLAG_DISCARD ,
+the discard of swap pages is controlled as follows:
+.RS 4n
+.IP SWAP_FLAG_DISCARD_ONCE 4n

This should use '.TP'. See man-pages(7):

Lists
There are different kinds of lists:

Tagged paragraphs
These are used for a list of tags and their descriptions. When the tags are constants (either macros or numbers) they are in bold. Use the .TP macro.

An example is this "Tagged paragraphs" subsection is it‐ self.

(You can look at the source code of man-pages(7) to see an example.)

Have a lovely day!
Alex

Quoted 20 lines
man/man2/swapon.2 +13 -0
+\- Discard only occurs when the swap area is first enabled
+with
+.BR swapon () .
+Minimum overhead is incurred for subsequent swap page frees.
+.IP SWAP_FLAG_DISCARD_PAGES 4n
+\- Discard occurs on every swap page free, asynchronously.
+This may incur significant overhead.
+.RE
+.P
+Setting both flags results in the behavior of
+.BR SWAP_FLAG_DISCARD_ONCE .
+Setting neither results in both types of discard being performed.
+.P
 See also NOTES.
 .P
 These functions may be used only by a privileged process (one having the
Signature · 1 line
2.51.0
Signature · 2 lines
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).