Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

swap(8)

Name

swap - swap administrative interface

Synopsis

/usr/sbin/swap -a swapname [swaplow] [swaplen]
/usr/sbin/swap -d swapname [swaplow]
/usr/sbin/swap -l [-h | -k | --scale[=item1,item2,...]]
/usr/sbin/swap -s [-h | --scale[=item1,item2,...]]

Description

The swap utility provides a method of adding, deleting, and monitoring the system swap areas used by the memory manager.

Options

The following options are supported:

–a swapname [swaplow] [swaplen]

Add the specified swap area. This option can only be used by an administrator who is assigned the File System Management rights profile or by root. swapname is the name of the swap area or regular file. On a system running a ZFS file system, specify a ZFS volume, such as /dev/zvol/dsk/rpool/swap, for a swap area. Using a regular file for swap is not supported on a ZFS file system. In addition, you cannot use the same ZFS volume for both the swap area and a dump device.

swaplow is the offset in 512-byte blocks into the file where the swap area should begin. swaplen is the desired length of the swap area in 512-byte blocks. The value of swaplen can not be less than 16. For example, if n blocks are specified, then (n-1) blocks would be the actual swap length. swaplen must be at least one page in length. The size of a page of memory can be determined by using the pagesize command. See pagesize(1). If the swap file is not a ZFS volume or lofi device the first page of a swap file is automatically skipped, and as a swap file needs to be at least one page in length, the minimum size should be a multiple of 2 pagesize bytes. The size of a page of memory is machine-dependent.

swaplow + swaplen must be less than or equal to the size of the swap file. If swaplen is not specified, an area will be added starting at swaplow and extending to the end of the designated file. If neither swaplow nor swaplen are specified, the whole file or device will be used. For swap files that are not ZFS volume or lofi devices the first page is skipped to protect any label that might be present.

Swap areas are added automatically during system startup by the svc:/system/swap service. This service adds all swap areas which have been specified in the /etc/vfstab file. For the syntax of these specifications, see vfstab(5) man page.

ZFS volumes used as a swap device will always be encrypted regardless of the value of the encryption property for the ZFS volume. See zfs_encrypt(8).

To use an NFS or local file system swapname, you should first create a file using mkfile(8). A local file system swap file can now be added to the running system by just running the swap –a command. For NFS mounted swap files, the server needs to export the file. Do this by performing the following steps:

  1. Run this on NFS server:

    share -F nfs -o  \
    rw=clientname,root=clientname directory-with-swap-file 
  2. Have the client add the following lines to /etc/vfstab:

    server:directory-with-swap-file -
    local-path-to-directory nfs    -   yes   -
    local-path-to-directory/swap-file -  -
    swap   - no    - 
  3. Enable NFS client service on the client:

    svcadm enable nfs/client
  4. Reboot the client.

–d swapname

Delete the specified swap area. This option can only be used by an administrator who is assigned the File System Management rights profile or by root. swapname is the name of the swap file: for example, /dev/dsk/c0t0d0s1 or a regular file. swaplow is the offset in 512-byte blocks into the swap area to be deleted. If swaplow is not specified, the area will be deleted starting at the second page. When the command completes, swap blocks can no longer be allocated from this area and all swap blocks previously in use in this swap area have been moved to other swap areas.

–h

All sizes are scaled to a human readable format. The –h option is equivalent to using the –scale=max,1024 option.

–k

Write the files sizes in units of 1024 bytes.

–l

List the status of all the swap areas. The output has these columns:

path

The path name for the swap area.

dev

The major/minor device number in decimal if it is a block special device; zeroes otherwise.

swaplo

The swaplow value for the area in 512-byte blocks.

blocks

The swaplen value for the area in 512-byte blocks.

free

The number of 512-byte blocks in this area that are not currently allocated.

encrypted

Shows yes if the device is encrypted and no otherwise.

The list does not include swap space in the form of physical memory because this space is not associated with a particular swap area.

If swap –l is run while swapname is in the process of being deleted (by swap –d), the string INDEL will appear in a seventh column of the swap stats.

–s

Print summary information about total swap space usage and availability:

allocated

The total amount of swap space in bytes currently allocated for use as backing store.

reserved

The total amount of swap space in bytes not currently allocated, but claimed by memory mappings for possible future use.

used

The total amount of swap space in bytes that is either allocated or reserved.

available

The total swap space in bytes that is currently available for future reservation and allocation.

These numbers include swap space from all configured swap areas as listed by the –l option, as well as swap space in the form of physical memory.

–scale[=item1,item2,...]

All sizes are scaled to a human readable format. Scaling is done by repetitively dividing by 1024, unless otherwise specified.

–scale specified without arguments enables default scaled output, and is equivalent to –scale=max,1024.

–scale can be specified with the following arguments.

binary

Scaling is done by repetitively dividing by a scale factor of 1024. The use of binary scaling is indicated by the addition of an 'i' modifier to the suffix (Ki, Mi, Gi, ...).

max

Values are scaled to the largest unit for which the result retains a non-zero integer part. Up to 2 decimal places of fractional output may be shown.

min

Values are scaled to the smallest unit capable of showing the full value within the allotted space of 5 columns, and displayed without the use of fractional output.

minwide

Values are scaled to the smallest unit capable of showing the full value within the allotted space of 8 columns, and displayed without the use of fractional output.

1000

Scaling is done by repetitively dividing by a scale factor of 1000.

1024

Scaling is done by repetitively dividing by a scale factor of 1024.

Usage

A block device larger than 2 Gbytes can be fully utilized for swap up to 263 −1 bytes.

Environment Variables

See environ(7) for descriptions of the following environment variables that affect the execution of swap: LC_CTYPE and LC_MESSAGE.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/core-os

See Also

pagesize(1), getpagesize(3C), vfstab(5), attributes(7), mkfile(8), shareall(8), zfs(8), zfs_encrypt(8)

Notes

For information about setting up a swap area with ZFS, see the book Managing ZFS File Systems in Oracle Solaris 11.4.

Warnings

No check is done to determine if a swap area being added overlaps with an existing file system.

History

Support for the –scale option was added to the swap command in Oracle Solaris 11.4.30.

The encrypted column was added to the output of the –l option in Oracle Solaris 11.4.24.

The –h and –k options were added to the swap command in Oracle Solaris 11.0, thanks to a contribution by Yann Poupet to the OpenSolaris project.

The swap command; with support for the –a, –d, –l, and –s options; was added to Solaris in the Solaris 2.0 release, replacing the swapon command used in SunOS 4.