.\" 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 "25 March 1999" "Linux 2.2.4" "Linux Programmer's Manual"
+.TH MKSWAP 8 "March 2009" "util-linux" "System Administration"
.SH NAME
mkswap \- set up a Linux swap area
.SH SYNOPSIS
-.BI "mkswap [\-c] [\-f] [\-p " PSZ "] [\-L " label "] [\-U " uuid "] " device " [" size "]"
+.B mkswap
+[options]
+.I device
+.RI [ size ]
.SH DESCRIPTION
.B mkswap
sets up a Linux swap area on a device or in a file.
-(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.)
-
The
.I device
argument will usually be a disk partition (something like
-.I /dev/hda4
-or
.IR /dev/sdb7 )
but can also be a file.
-The Linux kernel does not look at partition Id's, but
+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.
-(Warning: Solaris also uses this type. Be careful not to kill
-your Solaris partitions.)
+(\fBWarning: Solaris also uses this type. Be careful not to kill
+your Solaris partitions.\fP)
The
.I size
(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.)
-The
-.I PSZ
-parameter specifies the page size to use. It is almost always
-unnecessary (even unwise) to specify it, but certain old libc
-versions lie about the page size, so it is possible that
+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
+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
-gets it wrong. The symptom is that a subsequent
+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
-fails because no swap signature is found. Typical values for
-.I PSZ
-are 4096 or 8192.
-
-Linux knows about two styles of swap areas, old style and new style.
-The last 10 bytes of the first page of the swap area distinguishes
-them: old style has `SWAP_SPACE', new style has `SWAPSPACE2' as
-signature.
-
-In the old style, the rest of this first page was a bit map,
-with a 1 bit for each usable page of the swap area.
-Since the first page holds this bit map, the first bit is 0.
-Also, the last 10 bytes hold the signature. So, if the page
-size is S, an old style swap area can describe at most
-8*(S-10)-1 pages used for swapping.
-With S=4096 (as on i386), the useful area is at most 133890048 bytes
-(almost 128 MiB), and the rest is wasted.
-On an alpha and sparc64, with S=8192, the useful area is at most
-535560992 bytes (almost 512 MiB).
-
-The old setup wastes most of this bitmap page, because zero bits
-denote bad blocks or blocks past the end of the swap space,
-and a simple integer suffices to indicate the size of the swap space,
-while the bad blocks, if any, can simply be listed. Nobody wants
-to use a swap space with hundreds of bad blocks. (I would not even
-use a swap space with 1 bad block.)
-In the new style swap area this is precisely what is done.
+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.
-It is roughly 2GiB on i386, PPC, m68k, ARM, 1GiB on sparc, 512MiB on mips,
-128GiB on alpha and 3TiB on sparc64. For kernels after 2.3.3 there is no
-such limitation.
-Note that before 2.1.117 the kernel allocated one byte for each page,
-while it now allocates two bytes, so that taking a swap area of 2 GiB
-in use might require 2 MiB of kernel memory.
+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 (this was 8 before Linux 2.4.10).
+Presently, Linux allows 32 swap areas.
The areas in use can be seen in the file
.I /proc/swaps
-(since 2.1.25).
.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 setup a swap file, it is necessary to create that file before
+To set up a swap file, it is necessary to create that file before
initializing it with
-.B mkswap ,
-e.g. using a command like
+.BR mkswap ,
+e.g.\& using a command like
.nf
.RS
-# dd if=/dev/zero of=swapfile bs=1024 count=65536
+# fallocate \-\-length 8GiB swapfile
.RE
.fi
-Note that a swap 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).
-
-.SH OPTIONS
-.TP
-.B \-c
-Check the device (if it is a block device) for bad blocks
-before creating the swap area.
-If any are found, the count is printed.
-.TP
-.B \-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.
-On SPARC, force creation of the swap area.
-Without this option
-.B mkswap
-will refuse to create a v0 swap on a device with a valid SPARC superblock,
-as that probably means one is going to erase the partition table.
-.TP
-.BI "\-p " PSZ
-Specify the page size to use.
-.TP
-.BI "\-L " label
-Specify a label, to allow swapon by label.
-(Only for new style swap areas.)
-.TP
-.B \-v0, \-v1
-Specify the swap space version. This option is deprecated and \-v1 is
-supported only.
-
-The kernel has not supported v0 swap space format since 2.5.22. The new version
-v1 is supported since 2.1.117.
-
-The new v1 style header does not touch the first block, so may be
-preferable, in case you have a boot loader or disk label there.
+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.
-.TP
-.B \-U uuid
-Specify the uuid to use. The default is to generate UUIDs.
+.SH ENVIRONMENT
+.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-ng package and is available from
-ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/.
+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