path: root/static/netbsd/man8/swapctl.8

.\"	$NetBSD: swapctl.8,v 1.52 2026/02/17 12:24:45 kre Exp $
.\"
.\" Copyright (c) 1997 Matthew R. Green
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd February 16, 2026
.Dt SWAPCTL 8
.Os
.Sh NAME
.Nm swapctl ,
.Nm swapon
.Nd system swap management tool
.Sh SYNOPSIS
.Nm
.Fl A
.Op Fl f Ns \||\| Ns Fl o
.Op Fl n
.Op Fl p Ar priority
.Op Fl t Cm blk Ns \||\| Ns Cm noblk Ns \||\| Ns Cm auto
.Nm
.Fl D Ar dumpdev Ns \||\| Ns Cm none
.Nm
.Fl U
.Op Fl n
.Op Fl t Cm blk Ns \||\| Ns Cm noblk Ns \||\| Ns Cm auto
.Nm
.Fl a
.Op Fl p Ar priority
.Ar path
.Nm
.Fl c
.Fl p Ar priority
.Ar path
.Nm
.Fl d
.Ar path
.Nm
.Fl l Ns \||\| Ns Fl s
.Op Fl k Ns \||\| Ns Fl m Ns \||\| Ns Fl g Ns \||\| Ns Fl h
.Op Fl p Ar priority
.Nm
.Fl q
.Nm
.Fl z
.Pp
.Nm swapon
.Fl a
.Op Fl t Cm blk Ns \||\| Ns Cm noblk
.Nm swapon
.Ar path
.
.Sh DESCRIPTION
The
.Nm
program adds, removes,
lists, and prioritizes swap devices and files for the system.
.Pp
The historic
.Nm swapon
program, with
.Fl a
acts the same as
.Nm
.Fl A
.Pq Dq all ,
otherwise,
.Nm swapon
.Ar path
acts the same as
.Nm
.Fl a
.Ar path
.Pq Dq add .
.Pp
The following options are available for
.Nm :
.Bl -tag -width Fl
.
.It Fl A
Read the
.Pa /etc/fstab
file for devices and files with a
.Ql sw
or
.Ql dp
type, and add all
.Ql sw
type entries as swap devices and set the last
.Ql dp
type entry as the dump device.
If no swap devices are configured,
.Nm
will exit with an error code.
If used together with
.Fl t Cm auto
this option will not read
.Pa /etc/fstab
but query the kernel for all swap partitions on local hard disks.
.
.It Fl a
Add
.Ar path
to the kernel's list of swap devices.
.
.It Fl c
Change the priority of the 
.Ar path
swap device or file.
.
.It Fl D
The kernel dump device is set to
.Ar dumpdev ,
which must be a local block device, not a file.
The word
.Cm none
can be used instead to disable the currently set dump device.
The dump device is used when the system crashes
to write a current snapshot of real memory, to be saved later with
.Xr savecore 8
at system reboot, and analyzed to determine the problem.
.
.It Fl d
Remove
.Ar path
from the kernel's list of swap devices or files.
.
.It Fl f
Used in combination with
.Fl A Fl t Cm auto ,
.Fl f
causes
.Nm
to use the first discovered swap device as the dump device.
The
.Fl f
option is mutually exclusive with
.Fl o .
.
.It Fl g
Report sizes in GB (1024 * 1024 * 1024) blocks instead of the default
512 byte.
.
.It Fl h
Use
.Xr humanize_number 3
to display the sizes.
.
.It Fl k
Report sizes in KB (1024) blocks instead of the default 512 byte.
.
.It Fl l
List the current swap devices and files, and their usage statistics.
.
.It Fl m
Report sizes in MB (1024 * 1024) blocks instead of the default 512 byte.
.
.It Fl n
Dry run.
With the
.Fl A
or
.Fl U
options, print the action
.Nm
would take, but don't actually change any swap or dump devices.
.
.It Fl o
Similar to the
.Fl f
option, this
.Dq dump only
option makes
.Nm
find the first swap device and configure it as the dump device.
No swap device is changed.
This option needs to be used in combination with
.Fl A Fl t Cm auto
and is mutually exclusive with
.Fl f .
.
.It Fl p
Specify the
.Ar priority
of swap devices or files.
With
.Fl a
and
.Fl c
set the priority of the specified
.Ar path .
With
.Fl A
the
.Ar priority
becomes the default for
.Pa /etc/fstab
entries that do not specify a priority.
With the
.Fl l
and
.Fl s
the output is limited to only devices (or files) with the given
.Ar priority .
.
.It Fl q
Query
.Pa /etc/fstab ,
checking for any defined swap or dump devices.
If any are found,
.Nm
returns with an exit status of 0, if none are found the exit status will
be 1.
.
.It Fl s
Display a single line summary of current swap statistics.
.
.It Fl t
Specify the type of device to add or remove.
An argument of
.Cm blk
causes all block devices in
.Pa /etc/fstab
to be added (or removed).
An argument of
.Cm noblk
operates on all non-block devices in
.Pa /etc/fstab .
An argument of
.Cm auto
causes all swap partitions on local hard disks to be used.
The latter is useful in early system startup, where swapping
may be needed before all file systems are available, such as during
disk checks of large file systems.
.
.It Fl U
Read the
.Pa /etc/fstab
file for devices and files with an
.Ql sw
type, and remove all these entries as swap devices.
If no swap devices are unconfigured,
.Nm
will exit with an error code.
If used together with
.Fl t Cm auto
this option will not read
.Pa /etc/fstab
but unconfigure all local swap partitions.
.
.It Fl z
Display the current dump device.
.El
.
.Ss Swap Priority
The
.Nx
swap system allows different swap devices and files to be assigned different
priorities, to allow the faster resources to be used first.
Swap devices at the same priority are used in a round-robin fashion until
there is no more space available at this priority, when the next priority
level will be used.
The default priority is 0, the highest.
This value can be any valid integer,
with higher values receiving less priority.
.Ss Swap Options
When parsing the
.Pa /etc/fstab
file for swap devices, the following options are recognized:
.Pp
.Bl -tag -width nfsmntpt=/path
.It Li priority= Ns Ar N
Set the priority of the specified swap device to
.Ar N .
.It Li nfsmntpt= Ns Ar /path
Specify the local mount point when swapping to an NFS file.
The mount point must exist as a directory.
Typically, once this mount has succeeded, the file to be used for swapping
on will be available under this mount point.
For example:
.Bd -literal
server:/export/swap/client none swap sw,nfsmntpt=/swap
.Ed
.El
.Sh EXIT STATUS
If the requested operation was successful, the
.Nm
utility exits with status 0.
If an error occurred, the exit status is 1.
.Pp
The
.Fl A
and
.Fl U
operations (add or remove swap devices listed in
.Xr fstab 5 )
return an exit status of 2
to report that no suitable swap devices were found.
.Pp
The
.Fl z
operation (query dump device) and
.Fl l
(list swap partitions) return an exit status of 1 if no dump device or
swap partition has been configured.
If any swap partition is available or
a dump device is set, the respective query returns 0.
.Sh SEE ALSO
.Xr swapctl 2 ,
.Xr fstab 5 ,
.Xr mount_nfs 8
.Sh HISTORY
The
.Nm
program was first made available in
.Nx 1.3 .
The original
.Nm swapon
program, provided for backwards compatibility, appeared in
.Bx 4.0 .
.Sh AUTHORS
The
.Nm
program was written by
.An Matthew R. Green Aq Mt mrg@eterna23.net .
.Sh CAVEATS
Using the automatic swap partition detection done by the
.Fl A Fl t Cm auto
option may be dangerous.
Depending on the on-disk partitioning scheme used, the type of a partition
may not be accurately recognizable as a swap partition.
The autodetection might recognize and use partitions on
removable media like USB sticks.
An easy way to test the autoconfiguration is to use
.Nm
with the
.Fl n
option.
.Sh BUGS
If no swap information is specified in
.Pa /etc/fstab ,
the system startup scripts (see
.Xr rc 8 )
will configure no swap space and the system will behave very badly
if (more likely when) it runs out of real memory.
.Pp
Local and remote swap files cannot be configured until after the file
systems they reside upon are mounted read/write.
The system startup scripts need to
.Xr fsck 8
all local file systems before this can happen.
This process requires substantial amounts of memory on some systems.
If no local block swap devices are configured on a machine that has local
file systems to check, and relies only on swap files, the machine will have
no swap space at all during system
.Xr fsck 8
and may run out of real memory, causing fsck to abnormally exit and
the startup scripts to fail.
.Pp
Which device is
.Dq first
for the purposes of
.Fl Aft Ns Cm auto
or
.Fl Aot Ns Cm auto
is not specified, and depends upon system configuration behavior.