.\"
.\" @(#)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 "July 2014" "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
-.BR swapon
+.B swapon
[options]
.RI [ specialfile ...]
.br
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
.TP
.BR \-f , " \-\-fixpgsz"
-Reinitialize (exec /sbin/mkswap) the swap space if its page size does not
+Reinitialize (exec mkswap) the swap space if its page size does not
match that of the current running kernel.
-.BR mkswap (2)
+.BR mkswap (8)
initializes the whole device and does not check for bad blocks.
.TP
.BR \-h , " \-\-help"
is needed.)
.TP
.BR \-o , " \-\-options " \fIopts\fP
-Specify swap options by fstab compatible comma separated string. For example:
+Specify swap options by an fstab-compatible comma-separated string.
+For example:
.RS
.RS
.sp
-.B "swapon -o pri=1,discard=pages,nofail /dev/sda2"
+.B "swapon \-o pri=1,discard=pages,nofail /dev/sda2"
.sp
.RE
-The \fIopts\fP string is evaluated as the last and overrides all another
-options.
+The \fIopts\fP string is evaluated last and overrides all other
+command line options.
.RE
.TP
.BR \-p , " \-\-priority " \fIpriority\fP
to the option field of
.I /etc/fstab
for use with
-.BR "swapon -a" .
-When priority is not defined it defaults to \-1.
+.BR "swapon \-a" .
+When no priority is defined, it defaults to \-1.
.TP
.BR \-s , " \-\-summary"
Display swap usage summary by device. Equivalent to "cat /proc/swaps".
-Not available before Linux 2.1.25. This output format is DEPRECATED in favour
+This output format is DEPRECATED in favour
of \fB\-\-show\fR that provides better control on output data.
.TP
-.BR " \-\-show" [ =\fIcolumn\fR]
-Display definable table of swap areas. See
+.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
.B \-\-show
Use the partition that has the specified
.IR uuid .
.TP
-.B "\-v, \-\-verbose"
+.BR \-v , " \-\-verbose"
Be verbose.
.TP
-.B "\-V, \-\-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
-.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
-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 fstab (5),
-.BR init (8),
-.BR mkswap (8),
-.BR rc (8),
-.BR mount (8)
.SH FILES
.br
.I /dev/sd??
.br
.I /etc/fstab
ascii filesystem description table
+.SH NOTES
+.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 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.
.SH HISTORY
The
.B swapon
command appeared in 4.0BSD.
+.SH SEE ALSO
+.BR swapoff (2),
+.BR swapon (2),
+.BR fstab (5),
+.BR init (8),
+.BR fallocate (1),
+.BR mkswap (8),
+.BR mount (8),
+.BR rc (8)
.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/.
projects / thirdparty / util-linux.git / blobdiff