-.\" Copyright 1992, 1993 Rickard E. Faith (faith@cs.unc.edu)
+.\" Copyright 1998 Andries E. Brouwer (aeb@cwi.nl)
+.\"
.\" May be distributed under the GNU General Public License
-.\" Modified with suggestions from Linus, Mon Feb 1 21:40:49 1993
-.\" Modified with patches from Kai, Wed Jun 22 21:54:56 1994
-.\" Patches from jaggy@purplet.demon.co.uk (Mike Jagdis), Wed Feb 8 1995
-.\" Added comments from Nick Holloway, Sat Feb 11 1995, faith@cs.unc.edu
-.\" "
-.TH MKSWAP 8 "8 February 1995" "Linux 1.0" "Linux Programmer's Manual"
+.\"
+.TH MKSWAP 8 "March 2009" "util-linux" "System Administration"
.SH NAME
-mkswap \- set up a Linux swap device
+mkswap \- set up a Linux swap area
.SH SYNOPSIS
-.B "mkswap [ \-c ]"
-.IB device " [" size-in-blocks "]"
+.B mkswap
+[options]
+.I device
+.RI [ size ]
.SH DESCRIPTION
.B mkswap
-sets up a Linux swap area on a device (usually a disk partition).
+sets up a Linux swap area on a device or in a file.
The
.I device
-is usually of the following form:
-
-.nf
-.RS
-/dev/hda[1-8]
-/dev/hdb[1-8]
-/dev/sda[1-8]
-/dev/sdb[1-8]
-.RE
-.fi
+argument will usually be a disk partition (something like
+.IR /dev/sdb7 )
+but can also be a file.
+The Linux kernel does not look at partition IDs, but
+many installation scripts will assume that partitions
+of hex type 82 (LINUX_SWAP) are meant to be swap partitions.
+(\fBWarning: Solaris also uses this type. Be careful not to kill
+your Solaris partitions.\fP)
The
-.I size-in-blocks
-parameter is the desired size of the file system, in blocks. This
-information is determined automatically by mkswap if it is omitted. Block
-counts are rounded down to pages of 4 kB each. Only block counts equal to
-or greater than 40 and equal to or less than 131072 are allowed. Block
-counts greater than 130752 are (silently) rounded down to 130752.
-
-As Nick Holloway explains, the actual maximum for each swap file/partition
-is:
-.RS
-(4096 - 10) * 8 * 4096 = 133890048 bytes = 130752 blocks = 127.6875 Mb
-.RE
-This is because a single page is used to hold the swap bitmap at the
-start of the partition, where each bit is a single 4K page. The reason
-for the -10, is that the signature is "SWAP-SPACE" -- 10 characters.
+.I size
+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 \(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
+command in some boot script.
+
+.SH WARNING
+The swap header does not touch the first block. A boot loader or disk label
+can be there, but it is not a recommended setup. The recommended setup is to
+use a separate partition for a Linux swap area.
+
+.BR mkswap ,
+like many others mkfs-like utils,
+.B erases the first partition block to make any previous filesystem invisible.
+
+However,
.B mkswap
-can also set up swap files, although the file has to be created first. A
-sequence of commands similar to the following is reasonable for this
-purpose:
+refuses to erase the first block on a device with a disk
+label (SUN, BSD, \&...\&).
+
+.SH OPTIONS
+.TP
+.BR \-c , " \-\-check"
+Check the device (if it is a block device) for bad blocks
+before creating the swap area.
+If any bad blocks are found, the count is printed.
+.TP
+.BR \-f , " \-\-force"
+Go ahead even if the command is stupid.
+This allows the creation of a swap area larger than the file
+or partition it resides on.
+
+Also, without this option,
+.B mkswap
+will refuse to erase the first block on a device with a partition table.
+.TP
+.BR \-L , " \-\-label " \fIlabel\fR
+Specify a \fIlabel\fR for the device, to allow
+.B swapon
+by label.
+.TP
+.BR \-p , " \-\-pagesize " \fIsize\fR
+Specify the page \fIsize\fR (in bytes) to use. This option is usually unnecessary;
+.B mkswap
+reads the size from the kernel.
+.TP
+.BR \-U , " \-\-uuid " \fIUUID\fR
+Specify the \fIUUID\fR to use. The default is to generate a UUID.
+.TP
+.BR \-v , " \-\-swapversion 1"
+Specify the swap-space version. (This option is currently pointless, as the old
+.B \-v 0
+option has become obsolete and now only
+.B \-v 1
+is supported.
+The kernel has not supported v0 swap-space format since 2.5.22 (June 2002).
+The new version v1 is supported since 2.1.117 (August 1998).)
+.TP
+.BR \-h , " \-\-help"
+Display help text and exit.
+.TP
+.BR \-V , " \-\-version"
+Display version information and exit.
+
+.SH NOTES
+The maximum useful size of a swap area depends on the architecture and
+the kernel version.
+
+The maximum number of the pages that is possible to address by swap area header
+is 4294967295 (UINT_MAX). The remaining space on the swap device is ignored.
+
+Presently, Linux allows 32 swap areas.
+The areas in use can be seen in the file
+.I /proc/swaps
+
+.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 \(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
.nf
.RS
-# dd if=/dev/zero of=swapfile bs=1024 count=8192
-# mkswap swapfile 8192
-# sync
-# swapon swapfile
+# fallocate \-\-length 8GiB swapfile
.RE
.fi
-Note that the regular file has to be created before running
-.B mkswap
-on the file, and that the file must not contain any holes (so, using
+Note that a swap file must not contain any holes. Using
.BR cp (1)
-to create the file is not acceptable).
+to create the file is not acceptable. Neither is use of
+.BR fallocate (1)
+on file systems that support preallocated files, such as
+.BR XFS " or " ext4 ,
+or on copy-on-write filesystems like
+.BR btrfs .
+It is recommended to use
+.BR dd (1)
+and /dev/zero in these cases. Please read notes from
+.BR swapon (8)
+before adding a swap file to copy-on-write filesystems.
+
+.SH ENVIRONMENT
+.IP LIBBLKID_DEBUG=all
+enables libblkid debug output.
-.SH OPTIONS
-.TP
-.B \-c
-Check the device for bad blocks before creating the file system. If any
-are found, the count is printed. This option is meant to be used for swap
-partitions
-.BR only ,
-and should
-.B not
-be used for regular files! To make sure that regular files do not contain
-bad blocks, the partition that contains the regular file should have been
-created with
-.BR "mkfs -c" .
.SH "SEE ALSO"
-.BR fsck (8),
-.BR mkfs (8),
-.BR fdisk (8)
-.SH AUTHOR
-Linus Torvalds (torvalds@cs.helsinki.fi)
+.BR fdisk (8),
+.BR swapon (8)
+.SH AVAILABILITY
+The mkswap command is part of the util-linux package and is available from
+https://www.kernel.org/pub/linux/utils/util-linux/.
projects / thirdparty / util-linux.git / blobdiff