SWAPCTL(8) NetBSD System Manager's Manual SWAPCTL(8)
NAME
swapctl, swapon -- system swap management tool
SYNOPSIS
swapctl -A [-f|-o] [-n] [-p priority] [-t blk|noblk|auto] swapctl -D dumpdev|none swapctl -U [-n] [-t blk|noblk|auto] swapctl -a [-p priority] path swapctl -c -p priority path swapctl -d path swapctl -l|-s [-k|-m|-g|-h] [-p priority] swapctl -q swapctl -z swapon -a [-t blk|noblk] swapon path
DESCRIPTION
The swapctl program adds, removes, lists, and prioritizes swap devices and files for the system. The historic swapon program, with -a acts the same as swapctl -A (``all''), otherwise, swapon path acts the same as swapctl -a path (``add''). The following options are available for swapctl: -A Read the /etc/fstab file for devices and files with a `sw' or `dp' type, and add all `sw' type entries as swap devices and set the last `dp' type entry as the dump device. If no swap devices are configured, swapctl will exit with an error code. If used together with -t auto this option will not read /etc/fstab but query the kernel for all swap partitions on local hard disks. -a Add path to the kernel's list of swap devices. -c Change the priority of the path swap device or file. -D The kernel dump device is set to dumpdev, which must be a local block device, not a file. The word 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 savecore(8) at system reboot, and analyzed to determine the problem. -d Remove path from the kernel's list of swap devices or files. -f Used in combination with -A -t auto, -f causes swapctl to use the first discovered swap device as the dump device. The -f option is mutually exclusive with -o. -g Report sizes in GB (1024 * 1024 * 1024) blocks instead of the default 512 byte. -h Use humanize_number(3) to display the sizes. -k Report sizes in KB (1024) blocks instead of the default 512 byte. -l List the current swap devices and files, and their usage sta- tistics. -m Report sizes in MB (1024 * 1024) blocks instead of the default 512 byte. -n Dry run. With the -A or -U options, print the action swapctl would take, but don't actually change any swap or dump devices. -o Similar to the -f option, this ``dump only'' option makes swapctl 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 -A -t auto and is mutually exclusive with -f. -p Specify the priority of swap devices or files. With -a and -c set the priority of the specified path. With -A the priority becomes the default for /etc/fstab entries that do not specify a priority. With the -l and -s the output is limited to only devices (or files) with the given priority. -q Query /etc/fstab, checking for any defined swap or dump devices. If any are found, swapctl returns with an exit sta- tus of 0, if none are found the exit status will be 1. -s Display a single line summary of current swap statistics. -t Specify the type of device to add or remove. An argument of blk causes all block devices in /etc/fstab to be added (or removed). An argument of noblk operates on all non-block devices in /etc/fstab. An argument of 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. -U Read the /etc/fstab file for devices and files with an `sw' type, and remove all these entries as swap devices. If no swap devices are unconfigured, swapctl will exit with an error code. If used together with -t auto this option will not read /etc/fstab but unconfigure all local swap parti- tions. -z Display the current dump device. Swap Priority The NetBSD 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 fash- ion until there is no more space available at this priority, when the next priority level will be used. The default priority is 0, the high- est. This value can be any valid integer, with higher values receiving less priority. Swap Options When parsing the /etc/fstab file for swap devices, the following options are recognized: priority=N Set the priority of the specified swap device to N. nfsmntpt=/path Specify the local mount point when swapping to an NFS file. The mount point must exist as a directory. Typi- cally, once this mount has succeeded, the file to be used for swapping on will be available under this mount point. For example: server:/export/swap/client none swap sw,nfsmntpt=/swap
EXIT STATUS
If the requested operation was successful, the swapctl utility exits with status 0. If an error occurred, the exit status is 1. The -A and -U operations (add or remove swap devices listed in fstab(5)) return an exit status of 2 to report that no suitable swap devices were found. The -z operation (query dump device) and -l (list swap partitions) return an exit status of 1 if no dump device or swap partition has been config- ured. If any swap partition is available or a dump device is set, the respective query returns 0.
SEE ALSO
swapctl(2), fstab(5), mount_nfs(8)
HISTORY
The swapctl program was first made available in NetBSD 1.3. The original swapon program, provided for backwards compatibility, appeared in 4.0BSD.
AUTHORS
The swapctl program was written by Matthew R. Green <mrg@eterna23.net>.
CAVEATS
Using the automatic swap partition detection done by the -A -t 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 autoconfigura- tion is to use swapctl with the -n option.
BUGS
If no swap information is specified in /etc/fstab, the system startup scripts (see rc(8)) will configure no swap space and the system will behave very badly if (more likely when) it runs out of real memory. 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 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 fsck(8) and may run out of real memory, causing fsck to abnormally exit and the startup scripts to fail. Which device is ``first'' for the purposes of -Aftauto or -Aotauto is not specified, and depends upon system configuration behavior. NetBSD 11.99 February 16, 2026 NetBSD 11.99
Powered by man-cgi (2025-09-08). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.