swapctl(2)swapctl(2)NAMEswapctl - manage swap space
SYNOPSIS
#include <sys/stat.h>
#include <sys/swap.h>
int swapctl(int cmd, void *arg);
DESCRIPTIONswapctl 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>:
SC_ADD /* add a resource for swapping */
SC_LIST /* list the resources for swapping */
SC_REMOVE /* remove a resource for swapping */
SC_GETNSWP /* return number of swap resources */
SC_SGIADD /* add a resource for swapping */
SC_LREMOVE /* remove a resource for swapping */
SC_GETFREESWAP /* get amount of free swap */
SC_GETSWAPMAX /* get maximum amount of physical swap */
SC_GETSWAPVIRT /* get amount of virtual swap */
SC_GETRESVSWAP /* get amount of reserved logical swap */
SC_GETSWAPTOT /* get current amount of physical swap */
SC_GETLSWAPTOT /* get amount of logical swap */
When SC_SGIADD is specified, arg is a pointer to a xswapres structure
containing the following members:
char *sr_name; /* pathname of resource */
off_t sr_start; /* offset to start of swap area */
off_t sr_length; /* length of swap area */
off_t sr_maxlength;/* max length */
off_t sr_vlength; /* virtual length */
signed char sr_pri; /* priority */
sr_start, sr_maxlength, sr_vlength, and sr_length are specified in 512-
byte blocks. sr_length 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, sr_length, sr_maxlength, and sr_vlength are all set to
the size of the resource. sr_maxlength specifies the number of blocks
the specified resource should, if required, be grown to. This option is
currently unsupported, and sr_maxlength should always be set equal to
sr_length. sr_vlength specifies the number of blocks the system should
assume the new swap area can handle. Normally, this should be equal to
sr_length - meaning that the system will never over commit its memory
resources. If sr_vlength is set larger than sr_length, 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.
sr_pri set the priority of the new swap area. Swap areas with a higher
priority are allocated from first. If sr_pri 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 sr_start 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 sr_length, sr_vlength, and sr_maxlength
values will be rounded down to the next multiple of the system swap page
size.
When SC_ADD or SC_REMOVE is specified, arg is a pointer to a swapres
structure containing the following members:
char *sr_name; /* pathname of resource */
off_t sr_start; /* offset to start of swap area */
off_t sr_length; /* length of swap area */
sr_start and sr_length are specified in 512-byte blocks.
When SC_LIST is specified, arg is a pointer to a swaptable structure
containing the following members:
int swt_n; /* number of swapents following */
struct swapent swt_ent[];/* array of swt_n swapents */
A swapent structure contains the following members:
char *ste_path; /* name of the swap file */
off_t ste_start; /* starting block for swapping */
off_t ste_length; /* length of swap area */
long ste_pages; /* number of pages for swapping */
long ste_free; /* number of ste_pages free */
long ste_flags; /* ST_INDEL bit set if swap file */
/* is now being deleted */
long ste_vpages; /* virtual pages for swap */
long ste_maxpages;/* max pages swap can grow to */
short ste_lswap; /* logical swap # */
signed char ste_pri; /* swap resource priority */
Page 2
swapctl(2)swapctl(2)
SC_LIST causes swapctl to return at most swt_n entries. The return value
of swapctl is the number actually returned. The ST_INDEL bit is turned
on in ste_flags if the swap file is in the process of being deleted. The
ST_STALE bit is turned on in ste_flags 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
ST_LOCAL bit is turned on in ste_flags if the swap resource resides on a
local disk. The ST_IOERR bit is turned on in ste_flags 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
ST_EACCES bit is turned on in ste_flags 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 ST_BOOTSWAP bit is turned on in ste_flags if this
swap device was the initial swap device configured at boot time.
When SC_GETNSWP is specified, swapctl returns as its value the number of
swap resources in use. arg is ignored for this operation.
SC_LREMOVE causes swapctl removes the logical swap resource specified by
arg.
When SC_GETFREESWAP 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 ste_free value, converted to 512 byte blocks.
When SC_GETSWAPVIRT 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 ste_vpages value, converted to 512 byte blocks.
When SC_GETRESVSWAP 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 SC_GETLSWAPTOT minus the value returned by SC_SWAPMAX, there
is the potential for deadlock if every process suddenly requires all that
it has reserved.
When SC_GETLSWAPTOT 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 SC_GETSWAPTOT 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 ste_pages value, converted to 512 byte
blocks.
When SC_GETSWAPMAX 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 ste_maxpages 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 SC_GETSWAPTOT.
When specifying SC_GETFREESWAP, SC_GETSWAPVIRT, SC_GETRESVSWAP,
SC_GETLSWAPTOT, SC_GETSWAPTOT, or SC_GETSWAPMAX, arg should be a pointer
to a variable of type off_t.
The SC_SGIADD, SC_ADD, and SC_REMOVE 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
SC_ADD, SC_SGIADD, SC_GETRESVSWAP, SC_GETSWAPMAX, SC_GETSWAPVIRT,
SC_GETFREESWAP, SC_GETSWAPTOT, SC_GETLSWAPTOT, or SC_REMOVE, the number
of struct swapent entries actually returned for SC_LIST, or the number of
swap resources in use for SC_GETNSWP. 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 sr_start and sr_length is
already being used for swapping on the specified resource
(SC_ADD or SC_SGIADD).
EFAULT arg, sr_name, or ste_path points outside the allocated
address space.
EINVAL sr_length is not -1 and either sr_maxlength is not equal to
sr_length, or sr_vlength is less than either sr_length or
sr_maxlength.
ENXIO The pathname specified for SC_ADD or SC_SGIADD specifies a
non-configured block device or the block device does not have
a size routine.
EINVAL sr_pri is not equal to -1 and it greater than 7.
ENOSPC There are no more logical swap devices available (maximum
255) (SC_ADD or SC_SGIADD).
EBUSY The in-use pages for the swap area to be deleted cannot at
this time be reclaimed (SC_REMOVE or SC_LREMOVE).
EBUSY The specified resource is already in use as a swap area
(SC_ADD or SC_SGIADD).
EINVAL The specified function value is not valid, the path specified
is not a swap resource (SC_REMOVE), part of the range
specified by sr_start and sr_length lies outside the resource
specified (SC_ADD or SC_SGIADD), or the specified swap area
Page 4
swapctl(2)swapctl(2)
is less than one page (SC_ADD or SC_SGIADD).
EISDIR The path specified for SC_ADD or SC_SGIADD is a directory.
ELOOP Too many symbolic links were encountered in translating the
pathname provided to SC_ADD, SC_SGIADD, or SC_REMOVE .
ENAMETOOLONGThe length of a component of the path specified for SC_ADD,
SC_SGIADD, or SC_REMOVE exceeds {NAME_MAX} characters or the
length of the path exceeds {PATH_MAX} characters and
{_POSIX_NO_TRUNC} is in effect.
ENOENT The pathname specified for SC_ADD, SC_SGIADD, or SC_REMOVE
does not exist.
ENOMEM An insufficient number of struct swapent structures were
provided to SC_LIST, or there were insufficient system
storage resources available during an SC_ADD, SC_SGIADD, or
SC_REMOVE, or the system would not have enough swap space
after an SC_REMOVE.
ENOSYS The pathname specified for SC_ADD, SC_SGIADD, or SC_REMOVE 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 SC_ADD, SC_SGIADD, or SC_REMOVE
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 SC_ADD or SC_SGIADD is a read-only
file system.
Page 5
