From ec6f608028249480bae04c062089cb9120fcd8bd Mon Sep 17 00:00:00 2001

From: Karel Zak <kzak@redhat.com>

Date: Thu, 21 Mar 2019 13:21:54 +0100

Subject: [PATCH 180/185] swapon, mkswap: sync man page with upstream

Clean up all notes about swap-area restrictions (fallocate, XFS,

BTRFS, NFS, ...)

Addresses: https://bugzilla.redhat.com/show_bug.cgi?id=1203378

Signed-off-by: Karel Zak <kzak@redhat.com>

---

 disk-utils/mkswap.8 |  42 +++++-----

 sys-utils/swapon.8  | 186 ++++++++++++++++++++------------------------

 2 files changed, 104 insertions(+), 124 deletions(-)

diff --git a/disk-utils/mkswap.8 b/disk-utils/mkswap.8

index 6435dd6ae..b57433388 100644

--- a/disk-utils/mkswap.8

+++ b/disk-utils/mkswap.8

@@ -1,14 +1,13 @@

 .\" Copyright 1998 Andries E. Brouwer (aeb@cwi.nl)

 .\"

 .\" May be distributed under the GNU General Public License

-.\" Rewritten for 2.1.117, aeb, 981010.

 .\"

 .TH MKSWAP 8 "March 2009" "util-linux" "System Administration"

 .SH NAME

 mkswap \- set up a Linux swap area

 .SH SYNOPSIS

 .B mkswap

-.RI [ options ]

+[options]

 .I device

 .RI [ size ]

 .SH DESCRIPTION

@@ -32,14 +31,14 @@ parameter is superfluous but retained for backwards compatibility.

 (It specifies the desired size of the swap area in 1024-byte blocks.

 .B mkswap

 will use the entire partition or file if it is omitted.

-Specifying it is unwise -- a typo may destroy your disk.)

+Specifying it is unwise \(en a typo may destroy your disk.)

 After creating the swap area, you need the

 .B swapon

 command to start using it.  Usually swap areas are listed in

 .I /etc/fstab

 so that they can be taken into use at boot time by a

-.B swapon -a

+.B swapon \-a

 command in some boot script.

 .SH WARNING

@@ -54,7 +53,7 @@ like many others mkfs-like utils,

 However,

 .B mkswap

 refuses to erase the first block on a device with a disk

-label (SUN, BSD, ...).

+label (SUN, BSD, \&...\&).

 .SH OPTIONS

 .TP

@@ -103,48 +102,47 @@ Display version information and exit.

 .SH NOTES

 The maximum useful size of a swap area depends on the architecture and

 the kernel version.

-It is roughly 2GiB on i386, PPC, m68k and ARM, 1GiB on sparc, 512MiB on mips,

-128GiB on alpha, and 3TiB on sparc64.  For kernels after 2.3.3 (May 1999) there is no

-such limitation.

-Note that before version 2.1.117 the kernel allocated one byte for each page,

-while it now allocates two bytes, so that taking into use a swap area of 2 GiB

-might require 2 MiB of kernel memory.

+The maximum number of the pages that is possible to address by swap area header

+is 4294967295 (32-bit unsigned int).  The remaining space on the swap device is ignored.

-Presently, Linux allows 32 swap areas (this was 8 before Linux 2.4.10 (Sep 2001)).

+Presently, Linux allows 32 swap areas.

 The areas in use can be seen in the file

 .I /proc/swaps

-(since 2.1.25 (Sep 1997)).

 .B mkswap

 refuses areas smaller than 10 pages.

 If you don't know the page size that your machine uses, you may be

-able to look it up with "cat /proc/cpuinfo" (or you may not --

+able to look it up with "cat /proc/cpuinfo" (or you may not \(en

 the contents of this file depend on architecture and kernel version).

 To set up a swap file, it is necessary to create that file before

 initializing it with

 .BR mkswap ,

-e.g. using a command like

+e.g.\& using a command like

 .nf

 .RS

-# fallocate --length 8GiB swapfile

+# dd if=/dev/zero of=swapfile bs=1MiB count=$((8*1024))

 .RE

 .fi

-Note that a swap file must not contain any holes (so, using

-.BR cp (1)

-to create the file is not acceptable).

+to create 8GiB swapfile.

+

+Please read notes from

+.BR swapon (8)

+about

+.B the swap file use restrictions

+(holes, preallocation and copy-on-write issues).

 .SH ENVIRONMENT

-.IP LIBBLKID_DEBUG=0xffff

-enables debug output.

+.IP LIBBLKID_DEBUG=all

+enables libblkid debug output.

 .SH "SEE ALSO"

 .BR fdisk (8),

 .BR swapon (8)

 .SH AVAILABILITY

 The mkswap command is part of the util-linux package and is available from

-ftp://ftp.kernel.org/pub/linux/utils/util-linux/.

+https://www.kernel.org/pub/linux/utils/util-linux/.

diff --git a/sys-utils/swapon.8 b/sys-utils/swapon.8

index 836b17277..a45b38865 100644

--- a/sys-utils/swapon.8

+++ b/sys-utils/swapon.8

@@ -31,59 +31,24 @@

 .\"

 .\"     @(#)swapon.8	6.3 (Berkeley) 3/16/91

 .\"

-.\" Sun Dec 27 12:31:30 1992: Modified by faith@cs.unc.edu

-.\" Sat Mar  6 20:46:02 1993: Modified by faith@cs.unc.edu

-.\" Sat Oct  9 09:35:30 1993: Converted to man format by faith@cs.unc.edu

-.\" Sat Nov 27 20:22:42 1993: Updated authorship information, faith@cs.unc.edu

-.\" Mon Sep 25 14:12:38 1995: Added -v and -p information

-.\" Tue Apr 30 03:32:07 1996: Added some text from A. Koppenhoefer

-.\"

-.TH SWAPON 8 "September 1995" "util-linux" "System Administration"

+.TH SWAPON 8 "October 2014" "util-linux" "System Administration"

 .SH NAME

 swapon, swapoff \- enable/disable devices and files for paging and swapping

 .SH SYNOPSIS

-Get info:

-.br

-.in +5

-.B swapon \-s

-.RB [ \-h ]

-.RB [ \-V ]

-.sp

-.in -5

-Enable/disable:

-.br

-.in +5

 .B swapon

-.RB [ \-d ]

-.RB [ \-f ]

-.RB [ \-p

-.IR priority ]

-.RB [ \-v ]

-.IR specialfile ...

+[options]

+.RI [ specialfile ...]

 .br

 .B swapoff

-.RB [ \-v ]

-.IR specialfile ...

-.sp

-.in -5

-Enable/disable all:

-.br

-.in +5

-.B swapon \-a

-.RB [ \-e ]

-.RB [ \-f ]

-.RB [ \-v ]

-.br

-.B swapoff \-a

-.RB [ \-v ]

-.in -5

+.RB [ \-va ]

+.RI [ specialfile ...]

 .SH DESCRIPTION

 .B swapon

 is used to specify devices on which paging and swapping are to take place.

 The device or file used is given by the

 .I specialfile

-parameter. It may be of the form

+parameter.  It may be of the form

 .BI \-L " label"

 or

 .BI \-U " uuid"

@@ -105,82 +70,85 @@ flag is given, swapping is disabled on all known swap devices and files

 or

 .IR /etc/fstab ).

+.SH OPTIONS

 .TP

-.B "\-a, \-\-all"

+.BR \-a , " \-\-all"

 All devices marked as ``swap'' in

 .I /etc/fstab

 are made available, except for those with the ``noauto'' option.

 Devices that are already being used as swap are silently skipped.

 .TP

-.B "\-d, \-\-discard\fR [=\fIpolicy\fR]"

+.BR \-d , " \-\-discard" [ =\fIpolicy\fR]

 Enable swap discards, if the swap backing device supports the discard or

-trim operation. This may improve performance on some Solid State Devices,

-but often it does not. The option allows one to select between two

+trim operation.  This may improve performance on some Solid State Devices,

+but often it does not.  The option allows one to select between two

 available swap discard policies:

-.BI \-\-discard=once

+.B \-\-discard=once

 to perform a single-time discard operation for the whole swap area at swapon;

 or

-.BI \-\-discard=pages

-to discard freed swap pages before they are reused, while swapping.

+.B \-\-discard=pages

+to asynchronously discard freed swap pages before they are available for reuse.

 If no policy is selected, the default behavior is to enable both discard types.

 The

 .I /etc/fstab

 mount options

-.BI discard,

-.BI discard=once,

+.BR discard ,

+.BR discard=once ,

 or

-.BI discard=pages

-may be also used to enable discard flags.

+.B discard=pages

+may also be used to enable discard flags.

 .TP

-.B "\-e, \-\-ifexists"

+.BR \-e , " \-\-ifexists"

 Silently skip devices that do not exist.

 The

 .I /etc/fstab

 mount option

-.BI nofail

-may be also used to skip non-existing device.

+.B nofail

+may also be used to skip non-existing device.

 .TP

-.B "\-f, \-\-fixpgsz"

-Reinitialize (exec /sbin/mkswap) the swap space if its page size does not

+.BR \-f , " \-\-fixpgsz"

+Reinitialize (exec mkswap) the swap space if its page size does not

 match that of the current running kernel.

 .BR mkswap (2)

 initializes the whole device and does not check for bad blocks.

 .TP

-.B \-h, \-\-help

-Provide help.

+.BR \-h , " \-\-help"

+Display help text and exit.

 .TP

-.B "\-L \fIlabel\fP"

+.BI \-L " label"

 Use the partition that has the specified

 .IR label .

 (For this, access to

 .I /proc/partitions

 is needed.)

 .TP

-.B "\-p, \-\-priority \fIpriority\fP"

+.BR \-p , " \-\-priority " \fIpriority\fP

 Specify the priority of the swap device.

 .I priority

 is a value between \-1 and 32767.  Higher numbers indicate

 higher priority.  See

 .BR swapon (2)

-for a full description of swap priorities. Add

+for a full description of swap priorities.  Add

 .BI pri= value

 to the option field of

 .I /etc/fstab

 for use with

 .BR "swapon -a" .

-When priority is not defined it defaults to \-1.

+When no priority is defined, it defaults to \-1.

 .TP

-.B "\-s, \-\-summary"

-Display swap usage summary by device. Equivalent to "cat /proc/swaps".

-Not available before Linux 2.1.25.

+.BR \-s , " \-\-summary"

+Display swap usage summary by device.  Equivalent to "cat /proc/swaps".

+This output format is DEPRECATED in favour

+of \fB\-\-show\fR that provides better control on output data.

 .TP

-\fB\-\-show\fR [\fIcolumn,column\fR]

-Display definable device table similar to

-.B \-\-summary

-output.  See \-\-help output for

-.I column

-list.

+.BR \-\-show [ =\fIcolumn\fR ...]

+Display a definable table of swap areas.  See the

+.B \-\-help

+output for a list of available columns.

+.TP

+.B \-\-output\-all

+Output all available columns.

 .TP

 .B \-\-noheadings

 Do not print headings when displaying

@@ -195,51 +163,65 @@ output without aligning table columns.

 .B \-\-bytes

 Display swap size in bytes in

 .B \-\-show

-output instead of user friendly size and unit.

-.B "\-U \fIuuid\fP"

+output instead of in user-friendly units.

+.TP

+.BI \-U  " uuid"

 Use the partition that has the specified

 .IR uuid .

 .TP

-.B "\-v, \-\-verbose"

+.BR \-v , " \-\-verbose"

 Be verbose.

 .TP

-.B "\-V, \-\-version"

-Display version.

+.BR \-V , " \-\-version"

+Display version information and exit.

 .SH NOTES

-You should not use

-.B swapon

-on a file with holes.

-Swap over NFS may not work.

-.PP

+.SS Files with holes

+The swap file implementation in the kernel expects to be able to write to the

+file directly, without the assistance of the filesystem.  This is a problem on

+files with holes or on copy-on-write files on filesystems like Btrfs.

+.sp

+Commands like

+.BR cp (1)

+or

+.BR truncate (1)

+create files with holes.  These files will be rejected by swapon.

+.sp

+Preallocated files created by

+.BR fallocate (1)

+may be interpreted as files with holes too depending of the filesystem.

+Preallocated swap files are supported on XFS since Linux 4.18.

+.sp

+The most portable solution to create a swap file is to use

+.BR dd (1)

+and /dev/zero.

+.SS Btrfs

+Swap files on Btrfs are supported since Linux 5.0 on files with nocow attribute.

+See the

+.BR btrfs (5)

+manual page for more details.

+.SS NFS

+Swap over \fBNFS\fR may not work.

+.SS Suspend

 .B swapon

-automatically detects and rewrites swap space signature with old software

-suspend data (e.g S1SUSPEND, S2SUSPEND, ...). The problem is that if we don't

+automatically detects and rewrites a swap space signature with old software

+suspend data (e.g. S1SUSPEND, S2SUSPEND, ...). The problem is that if we don't

 do it, then we get data corruption the next time an attempt at unsuspending is

 made.

-.PP

-.B swapon

-may not work correctly when using a swap file with some versions of btrfs.

-This is due to the swap file implementation in the kernel expecting to be able

-to write to the file directly, without the assistance of the file system.

-Since btrfs is a copy-on-write file system, the file location may not be

-static and corruption can result. Btrfs actively disallows the use of files

-on its file systems by refusing to map the file. This can be seen in the system

-log as "swapon: swapfile has holes." One possible workaround is to map the

-file to a loopback device. This will allow the file system to determine the

-mapping properly but may come with a performance impact.

-

 .SH ENVIRONMENT

-.IP LIBMOUNT_DEBUG=0xffff

-enables debug output.

+.IP LIBMOUNT_DEBUG=all

+enables libmount debug output.

+.IP LIBBLKID_DEBUG=all

+enables libblkid debug output.

 .SH SEE ALSO

-.BR swapon (2),

 .BR swapoff (2),

+.BR swapon (2),

 .BR fstab (5),

 .BR init (8),

+.BR fallocate (1),

 .BR mkswap (8),

-.BR rc (8),

-.BR mount (8)

+.BR mount (8),

+.BR rc (8)

 .SH FILES

 .br

 .I /dev/sd??

@@ -253,4 +235,4 @@ The

 command appeared in 4.0BSD.

 .SH AVAILABILITY

 The swapon command is part of the util-linux package and is available from

-ftp://ftp.kernel.org/pub/linux/utils/util-linux/.

+https://www.kernel.org/pub/linux/utils/util-linux/.

-- 

2.20.1