swapctl(2) swapctl(2)
NAME
swapctl - manage swap space
SYNOPSIS
#include <sys/stat.h>
#include <sys/swap.h>
int swapctl(int cmd, void *arg);
DESCRIPTION
swapctl adds, deletes, or returns information about swap resources. Swap
resources can be local disk partitions (block devices), local file system
files, and files on file systems mounted via nfs. cmd specifies one of
the following options contained in <sys/swap.h>:
SCADD /* add a resource for swapping */
SCLIST /* list the resources for swapping */
SCREMOVE /* remove a resource for swapping */
SCGETNSWP /* return number of swap resources */
SCSGIADD /* add a resource for swapping */
SCLREMOVE /* remove a resource for swapping */
SCGETFREESWAP /* get amount of free swap */
SCGETSWAPMAX /* get maximum amount of physical swap */
SCGETSWAPVIRT /* get amount of virtual swap */
SCGETRESVSWAP /* get amount of reserved logical swap */
SCGETSWAPTOT /* get current amount of physical swap */
SCGETLSWAPTOT /* get amount of logical swap */
When SCSGIADD is specified, arg is a pointer to a xswapres structure
containing the following members:
char *srname; /* pathname of resource */
offt srstart; /* offset to start of swap area */
offt srlength; /* length of swap area */
offt srmaxlength;/* max length */
offt srvlength; /* virtual length */
signed char srpri; /* priority */
srstart, srmaxlength, srvlength, and srlength are specified in 512-
byte blocks. srlength specifies the number of blocks of the specified
resource that should be used for new swap area. It must be less than or
equal to the size of the resource (e.g. file size or partition size). If
a -1 is specified, srlength, srmaxlength, and srvlength are all set to
the size of the resource. srmaxlength specifies the number of blocks
the specified resource should, if required, be grown to. This option is
currently unsupported, and srmaxlength should always be set equal to
srlength. srvlength specifies the number of blocks the system should
assume the new swap area can handle. Normally, this should be equal to
srlength - meaning that the system will never over commit its memory
resources. If srvlength is set larger than srlength, then the system
believes that it has more swap space than it really does. As long as no
process actually requires that space, there is no problem. This permits
Page 1
swapctl(2) swapctl(2)
very large applications that wish to fork(2) but have no intention of
creating two large processes, to do so without requiring a lot of swap
space that is really not needed. It also permits applications that have
sparse data to effectively run on machines with small swap spaces.
Because the system can in fact over commit its memory resources,
deadlocks can result where there is no more memory and no more swap
space. These deadlocks are detected by the system and an appropriate
process is killed that will permit the system to continue operating.
srpri set the priority of the new swap area. Swap areas with a higher
priority are allocated from first. If srpri is set to -1 the system
will assign the priority based on the type of swap resource. Highest
priority (0) is the default for block devices. Priority 2 for local file
system files, and priority 4 for nfs mounted files.
The srstart value will be rounded up to the next multiple of the system
swap page size (4096 bytes or 16384 depending on the return value of the
getpagesize(2) system call). The srlength, srvlength, and srmaxlength
values will be rounded down to the next multiple of the system swap page
size.
When SCADD or SCREMOVE is specified, arg is a pointer to a swapres
structure containing the following members:
char *srname; /* pathname of resource */
offt srstart; /* offset to start of swap area */
offt srlength; /* length of swap area */
srstart and srlength are specified in 512-byte blocks.
When SCLIST is specified, arg is a pointer to a swaptable structure
containing the following members:
int swtn; /* number of swapents following */
struct swapent swtent[];/* array of swtn swapents */
A swapent structure contains the following members:
char *stepath; /* name of the swap file */
offt stestart; /* starting block for swapping */
offt stelength; /* length of swap area */
long stepages; /* number of pages for swapping */
long stefree; /* number of stepages free */
long steflags; /* STINDEL bit set if swap file */
/* is now being deleted */
long stevpages; /* virtual pages for swap */
long stemaxpages;/* max pages swap can grow to */
short stelswap; /* logical swap # */
signed char stepri; /* swap resource priority */
Page 2
swapctl(2) swapctl(2)
SCLIST causes swapctl to return at most swtn entries. The return value
of swapctl is the number actually returned. The STINDEL bit is turned
on in steflags if the swap file is in the process of being deleted. The
STSTALE bit is turned on in steflags if the swap file is on an NFS
mounted file system, and the file on the server was removed. No further
allocations will be made from a swap resource that has this bit set. The
STLOCAL bit is turned on in steflags if the swap resource resides on a
local disk. The STIOERR bit is turned on in steflags if any errors
have occurred when reading or writing the swap resource. Allocations
will still be satisfied from swap resources with this bit set. The
STEACCES bit is turned on in steflags if a permission error occurs when
attempting to write to the swap resource. This occurs most often when
user id 0 does not have the appropriate privileges on an NFS mounted file
system. No further allocations will be made from a swap resource that
has this bit set. The STBOOTSWAP bit is turned on in steflags if this
swap device was the initial swap device configured at boot time.
When SCGETNSWP is specified, swapctl returns as its value the number of
swap resources in use. arg is ignored for this operation.
SCLREMOVE causes swapctl removes the logical swap resource specified by
arg.
When SCGETFREESWAP is specified, swapctl copies the number of currently
free swap blocks (512 bytes) to the address given by arg. This is the
sum of each swap area's stefree value, converted to 512 byte blocks.
When SCGETSWAPVIRT is specified, swapctl copies the total number of
virtual swap blocks (512 bytes) to the address given by arg. This is the
sum of each swap area's stevpages value, converted to 512 byte blocks.
When SCGETRESVSWAP is specified, swapctl copies the number of logical
swap blocks (512 bytes) that have been reserved by all existing processes
to the address given by arg. When this value is greater than the value
returned by SCGETLSWAPTOT minus the value returned by SCSWAPMAX, there
is the potential for deadlock if every process suddenly requires all that
it has reserved.
When SCGETLSWAPTOT is specified, swapctl copies the current number of
logical swap blocks (512 bytes) to the address given by arg. This is
value is the sum of the amount of physical memory potentially available
for processes plus the number of virtual swap blocks plus the number of
physical swap blocks.
When SCGETSWAPTOT is specified, swapctl copies the current number of
physical swap blocks (512 bytes) to the address given by arg. This is
the sum of each swap area's stepages value, converted to 512 byte
blocks.
When SCGETSWAPMAX is specified, swapctl copies the maximum number of
swap blocks (512 bytes) to the address given by arg. This is the sum of
each swap area's stemaxpages value, converted to 512 byte blocks. Since
Page 3
swapctl(2) swapctl(2)
growable swap areas is not yet supported this value will always be the
same as that returned by SCGETSWAPTOT.
When specifying SCGETFREESWAP, SCGETSWAPVIRT, SCGETRESVSWAP,
SCGETLSWAPTOT, SCGETSWAPTOT, or SCGETSWAPMAX, arg should be a pointer
to a variable of type off_t.
The SCSGIADD, SCADD, and SCREMOVE functions will fail if the calling
process does not have appropriate privilege.
RETURN VALUE
Upon successful completion, the function swapctl returns a value of 0 for
SCADD, SCSGIADD, SCGETRESVSWAP, SCGETSWAPMAX, SCGETSWAPVIRT,
SCGETFREESWAP, SCGETSWAPTOT, SCGETLSWAPTOT, or SCREMOVE, the number
of struct swapent entries actually returned for SCLIST, or the number of
swap resources in use for SCGETNSWP. Upon failure, the function swapctl
returns a value of -1 and sets errno to indicate an error.
ERRORS
Under the following conditions, the function swapctl fails and sets errno
to:
EEXIST Part of the range specified by srstart and srlength is
already being used for swapping on the specified resource
(SCADD or SCSGIADD).
EFAULT arg, srname, or stepath points outside the allocated
address space.
EINVAL srlength is not -1 and either srmaxlength is not equal to
srlength, or srvlength is less than either srlength or
srmaxlength.
ENXIO The pathname specified for SCADD or SCSGIADD specifies a
non-configured block device or the block device does not have
a size routine.
EINVAL srpri is not equal to -1 and it greater than 7.
ENOSPC There are no more logical swap devices available (maximum
255) (SCADD or SCSGIADD).
EBUSY The in-use pages for the swap area to be deleted cannot at
this time be reclaimed (SCREMOVE or SCLREMOVE).
EBUSY The specified resource is already in use as a swap area
(SCADD or SCSGIADD).
EINVAL The specified function value is not valid, the path specified
is not a swap resource (SCREMOVE), part of the range
specified by srstart and srlength lies outside the resource
specified (SCADD or SCSGIADD), or the specified swap area
Page 4
swapctl(2) swapctl(2)
is less than one page (SCADD or SCSGIADD).
EISDIR The path specified for SCADD or SCSGIADD is a directory.
ELOOP Too many symbolic links were encountered in translating the
pathname provided to SCADD, SCSGIADD, or SCREMOVE .
ENAMETOOLONGThe length of a component of the path specified for SCADD,
SCSGIADD, or SCREMOVE exceeds {NAMEMAX} characters or the
length of the path exceeds {PATHMAX} characters and
{POSIXNOTRUNC} is in effect.
ENOENT The pathname specified for SCADD, SCSGIADD, or SCREMOVE
does not exist.
ENOMEM An insufficient number of struct swapent structures were
provided to SCLIST, or there were insufficient system
storage resources available during an SCADD, SCSGIADD, or
SCREMOVE, or the system would not have enough swap space
after an SCREMOVE.
ENOSYS The pathname specified for SCADD, SCSGIADD, or SCREMOVE is
not a file or block special device. The file system on which
pathname resides does not permit mapping or swapping.
ENOTDIR Pathname provided to SCADD, SCSGIADD, or SCREMOVE
contained a component in the path prefix that was not a
directory.
EPERM The process does not have appropriate privilege.
EROFS The pathname specified for SCADD or SCSGIADD is a read-only
file system.
Page 5