swap(1M)swap(1M)NAMEswap - swap administrative interface
SYNOPSIS
/sbin/swap -a [-i][-ppri][-vvlen] name [low [len]]
/sbin/swap -d name/lswap [low]
/sbin/swap -l [-n][-f][-b]
/sbin/swap -s [-b]
/sbin/swap -m
/sbin/swap -u
DESCRIPTIONswap provides a method of adding, deleting, and monitoring the system
swap areas used by the memory manager. The following options are
recognized:
-a Add the specified swap resource. name is the name of the block
special partition, for example, /dev/dsk/dks0d1s1 or a regular file.
Files on NFS mounted file systems are also permitted (see Swapping
to NFS Files below). low is the offset in 512-byte blocks into the
partition/file where the swap area should begin. If low is absent,
a default of 0 is used. This value is rounded up to a multiple of
the system defined swap page size. len is the length of the swap
area in 512-byte blocks. If len is absent, the new swap area will
use the entire partition/file. This value is rounded down to a
multiple of the system defined swap page size. Files used as swap
devices must exist and have been previously grown to the appropriate
size (see mkfile(1m)). A maximum of 255 swap resources can be
active at a given time. This option can only be used by a
privileged user.
Swap areas are normally added by modifying the /etc/fstab file to
contain the various files and partitions that should be added when
the system is booted.
When using the -a or -m option, /etc/fstab is scanned for an entry
whose type field contains swap and whose filesystem field matches
name. name is made into a full path name. If an entry is found in
/etc/fstab, any supplied options are used to supplement any options
given on the command line (e.g. priority).
-i Ignore safety checks. Normally, when adding a block special device
as a swap resource, a check is made to try to be certain that the
block device does not overlap any existing file systems. This
option turns off that check.
-p pri
Swap resources have a priority between 0 and 7 inclusive where lower
priority swap resources are allocated from first. Within a
priority, allocations are done round-robin. By default, block
devices are assigned a priority of 0, files on local file systems
are assigned a priority of 2 and files on NFS mounted file systems
Page 1
swap(1M)swap(1M)
are assigned a priority of 4. This option is only valid when adding
a swap resource.
-v vlength
Set the virtual length of the swap area to vlength. Normally, if
this field is not specified, the amount of logical swap is increased
by the size of the physical swap device being added. This option
tells the system to increase the logical swap amount by vlength.
Thus, the difference between vlength and the actual size of the
device is amount of virtual swap that is added. The virtual length
must be greater than or equal to the physical length of the swap
area. If not specified, the virtual length is set equal to the
actual length. See swapctl(2) for a discussion on virtual swap
spaces. In general, this option should only be used when there is
no other way to get enough swap resources (even via NFS) and it is
understood the potential problems creating virtual swap can cause.
See the discussion of Logical Swap Space below.
-d Delete the specified swap resource. name is the name of block
special partition, for example, /dev/dsk/dks0d1s1 or a regular file.
If name starts with a digit, it is interpreted as the logical swap
number of the device to be deleted. This is useful when the file or
device directory entry has been inadvertently been removed. low is
the offset in 512-byte blocks into the swap area to be deleted. If
not specified, a default of 0 is used. Using this option marks the
swap area as ``INDEL'' (in the process of being deleted). The
system will not allocate any new blocks from the area, and will try
to free swap blocks from it. The area will remain in use until all
blocks from it are freed. This option can be used only by a
privileged user.
-m Add all swap resources specified in /etc/fstab ( type field is
swap). An entry with the name /dev/swap is ignored, as are all
entries with the noauto option present. This option is primarily
for the system start up script /etc/init.d/swap which, at boot time,
adds all the administrator configured swap resources. This option
can be used only by a privileged user.
-u Delete all swap resources except the original boot swap resource.
This option is primarily for the system shutdown script
/etc/init.d/swap which, at system shutdown time, deletes all the
configured swap resources. The original boot swap resource may be
explicitly deleted using the -d option. This option can be used
only by a privileged user.
-l List the status of all the swap areas. The output has either seven
or nine columns depending on various options. By default, the
listing contains nine columns and all values are in 512 byte blocks.
The -n option enables a new easier to read output format which
defaults to printing the important seven columns (the additional two
columns are printed if the -f option is specified). Values with the
-n option are printed in either bytes, or with the -b option, in
Page 2
swap(1M)swap(1M)
512-byte blocks. The -f and -b options are only recognized when the
new output format is specified.
# The logical swap number. This ranges from 1 to 255. This
is column is labeled lswap in the default listing format.
path The path name for the swap area.
dev The major/minor device number in decimal. This is printed
in the default list format or in the new format if the -f
option is present. If the swap resource is a block special
device, this major/minor pair refers to the special device
itself. If the swap resource is a regular file, the
major/minor number is for the underlying file system that
the file resides on. If the stat(2) on path fails, '?,?' is
printed.
pri The priority of the swap resource.
swaplo The swaplow value for the area in 512-byte blocks. This is
printed in the default list format or in the new format if
the -f option is present. This value is rounded up to a
multiple of the system defined swap page size.
pswap The swaplen value for the area. This value is rounded down
to a multiple of the system defined swap page size. This is
column is labeled blocks in the default listing format.
free The amount of free swap in the area.
maxswap The maximum size the area will be grown to.
vswap The size over and above any physical space that the system
is assuming it can use (see the discussion of logical swap
space below, and the -v option above).
There are four status flags that may be printed after the last
column. Normally functioning swap resources will not have any
status flags. These flags are:
INDEL The swap area is being deleted. No allocations will be made
from this device.
EACCES The swap area was on an NFS mounted file system and 'root'
does not have permission to write the file. The swap area
is immediately taken off line.
ESTALE The swap area was on an NFS mounted file system and the file
was removed on the NFS server. The swap area is immediately
taken off line. Processes with pages on the swap area will
be terminated abnormally the first time they attempt to
access any page that had been stored on the swap area.
Page 3
swap(1M)swap(1M)
IOERR An I/O error occurred on the device. This could result in
the abnormal termination of a process. Look in
/var/adm/SYSLOG for more details. Even with I/O errors, the
swap area is still allocated from and used until deleted.
-s Print information about total logical swap space usage. Values are
printed in either bytes, or with the -b option, in 512-byte blocks.
allocated The amount of swap space allocated to private pages.
reserved The amount of swap space not currently allocated, but
claimed by private memory mappings.
used The total amount of logical swap space that is either
allocated or reserved.
available The total logical swap space that is currently available
for future reservation and allocation.
SWAPPING TO NFS FILES
Swapping to regular files on NFS mounted file systems is permitted but
should be done only with hard mounted file systems with the intr option
turned off (see fstab(4)). When using either soft mounted file systems
or the intr option, NFS may return an error during a swap I/O operation.
An I/O error that occurs when swapping in a page causes the process
requesting the page to be killed, since it's address space is no longer
accessible. Since it is possible for the init process to be swapped out
to the NFS file, a timeout from a soft mounted file system that occurs
while the system is swapping in a page for init will cause init to die.
Since the system is unable to run without init, the system will in turn
panic. Using hard mounted file systems without the intr flag avoids
these problems.
Even when using hard mounted NFS file systems, the system may appear to
hang if the NFS server fails to respond. If the window manager, shell,
or other key process is swapped out to the NFS file and the server fails
to respond during swap-in, then the system will wait and retry the NFS
file read indefinitely. During this time, programs attempting to swap-in
pages from that server will not run and will appear to be hung. Once the
NFS server starts responding again, normal system activity will resume.
Finally, the system administrator must ensure that the swap file on the
NFS server is not deleted. This would cause subsequent swap-ins to fail
and again cause the associated processes to be killed.
LOGICAL SWAP SPACE
Logical swap space is the sum total of physical memory (less space
occupied by the kernel) and all swap devices. The system reserves
logical swap space for the private portions of a process's virtual
address space (data, bss, stack, MAP_PRIVATE mmap mappings, etc.) when
virtual address spaces are created (via fork(2)), when they are grown
(via brk(2), sbrk(2), or malloc(3C)), or when new segments are attached
Page 4
swap(1M)swap(1M)
(via mmap(2), or shmat(2)). Logical swap space is not required for
shared text or MAP_SHARED mapped files (except for mappings of the
/dev/zero device). If the amount of private virtual space requested
exceeds the available logical swap space, the system call fails with
EAGAIN and an "out of logical swap space" message is logged on the
console. The system does this in order to prevent memory deadlocks from
occurring.
Note that the system may report being out of swap space when the -l
option shown above reports free swap space available. This happens when
the logical swap space has been reserved, but physical space has not yet
been allocated, so the blocks are still marked as being free. The -s
option to the swap command will report the amount of logical swap space
reserved and allocated.
Programs that have large address spaces and large programs that fork, may
receive EAGAIN along with the "out of logical swap space" message on the
console. This can also happen when debugging a large program with dbx or
other debugger. There are two ways to avoid this error: adding more real
swap space, or adding virtual swap space. Adding real swap space means
allocating an additional disk partition or a regular file (either local
or remote via NFS) to be used as a swap device (using the -a option shown
above and the examples below). This is the required approach for
programs that use most of the virtual addresses they allocate. The
advantage of this approach is that it continues to avoid memory
deadlocks, but requires physical disk space to be allocated.
The alternative is to add virtual swap space using the -v option. This
increases the amount of logical swap space without using any physical
disk space. This is suitable when the programs involved do not intend to
use the virtual address space they allocate (i.e., when the address space
is sparse or when a large program that forks intends to exec soon
afterwards without modifying many pages). In these cases, physical swap
space is not required and so adding virtual swap space allows the kernel
to complete the logical swap space reservation and avoid the EAGAIN
errors. The advantage of this approach is that it does not require any
disk space, but adds the risk of encountering a memory deadlock. Memory
deadlocks occur when the system has over-committed logical swap space by
allowing the total private virtual space of the processes on the system
to exceed real swap space. When processes attempt to use the allocated
virtual space, the kernel has no place to store the data (since virtual
swap space has no associated disk space), and a memory deadlock results.
In these instances, the kernel kills one or more processes to free up
enough logical swap space to break the deadlock. For this reason,
virtual swap space should not be used in cases where the program will
attempt to use the memory. For example, programs that expect malloc(3C)
to return NULL when there is no more memory will in fact be allocated
virtual memory that they could not use without causing a memory deadlock.
The -v option should therefore be used with care.
Page 5
swap(1M)swap(1M)NOTES
The ability to request that a swap resource be automatically grown has
not been implemented.
EXAMPLES
The following swap example requests 10K of swap area (twenty 512-byte
blocks) on the device /dev/dsk/dks0d1s1:
/sbin/swap -a /dev/dsk/dks0d1s1 0 20
The following adds 50Mb of swap space to the system using a file in the
/swap directory:
/usr/sbin/mkfile 50m /swap/swap1
/sbin/swap -a /swap/swap1
To make this swap area permanent (automatically added at boot time) add
the following line to /etc/fstab:
/swap/swap1 swap swap pri=3 0 0
The following example adds the regular file swap1 as a swap resource.
Its priority is set to 5, and the system is told that it should add 100
Mbytes (204800 512-byte blocks) to the virtual swap total. The example
assumes that swap1 is less than 100 Mbytes in length:
/sbin/swap -a -p 5 -v 204800 swap1
The following line in /etc/fstab will add the same swap resource as the
previous example, except that it will occur automatically at system
startup time:
/swap/swap1 swap swap pri=5,vlength=204800 0 0
FILES
/etc/fstab swap and/or vswap to add at system boot
/etc/config/vswap.options sets default size of virtual swap at boot
/etc/init.d/swap adds/removes swap and/or vswap at boot/shutdown
SEE ALSOmkfile(1M), mount(1M), swapctl(2), fstab(4).
Page 6
