420 lines
12 KiB
Groff
420 lines
12 KiB
Groff
.if n .pH g2.swapctl @(#)swapctl 41.1 of 3/4/91
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1989, 1990 AT&T
|
|
.\"ident "@(#)svid_rt:rt_os/swapctl 1.2"
|
|
.\" @(#)swapctl 1.4 88/09/26 SMI;
|
|
'\" macro stdmacro
|
|
.\" Sun's swapctl.3
|
|
'\"macro stdmacro
|
|
.nr X
|
|
.if \nX=0 .ds x} swapctl 2 "" "\&"
|
|
.if \nX=1 .ds x} swapctl 2 ""
|
|
.if \nX=2 .ds x} swapctl 2 "" "\&"
|
|
.if \nX=3 .ds x} swapctl "" "" "\&"
|
|
.TH \*(x}
|
|
.if '\*p'' \{\
|
|
.ds N
|
|
.ds p
|
|
.ds P
|
|
.SH NAME
|
|
\f4swapctl\f1 \- manage swap space
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft 4
|
|
#include <sys/stat.h>
|
|
#include <sys/swap.h>
|
|
.sp0.5
|
|
int swapctl(int cmd, void *arg);
|
|
.ft 1
|
|
.fi
|
|
.SH DESCRIPTION
|
|
\f4swapctl\f1 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.
|
|
\f2cmd\f1
|
|
specifies one of the following options
|
|
contained in
|
|
\f4<sys/swap.h>\f1:
|
|
.PP
|
|
.ta .5i 2.0i
|
|
.nf
|
|
.ft 4
|
|
.sp .5
|
|
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 */
|
|
.sp .5
|
|
.ft 1
|
|
.fi
|
|
.PP
|
|
When
|
|
\f4SC_SGIADD\f1
|
|
is specified,
|
|
\f2arg\f1
|
|
is a pointer to a
|
|
\f4xswapres\f1
|
|
structure containing the following members:
|
|
.PP
|
|
.ft 4
|
|
.nf
|
|
.ta .5i 1.7i 3i
|
|
.sp .5
|
|
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 */
|
|
.sp .5
|
|
.ft 1
|
|
.fi
|
|
.PP
|
|
\f4sr_start\fP, \f4sr_maxlength\fP, \f4sr_vlength\fP, and \f4sr_length\fP are specified in 512-byte blocks.
|
|
\f4sr_length\fP 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, \f4sr_length\fP, \f4sr_maxlength\fP, and \f4sr_vlength\fP
|
|
are all set to the size of the resource.
|
|
\f4sr_maxlength\fP specifies the number of blocks the specified
|
|
resource should, if required, be grown to.
|
|
This option is currently unsupported, and \f4sr_maxlength\fP should
|
|
always be set equal to \f4sr_length\fP.
|
|
\f4sr_vlength\fP specifies the number of blocks the system should
|
|
assume the new swap area can handle.
|
|
Normally, this should be equal to \f4sr_length\fP - meaning that the
|
|
system will never over commit its memory resources.
|
|
If \f4sr_vlength\fP is set larger than \f4sr_length\fP, 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 very large applications that wish to
|
|
.IR 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.
|
|
\f4sr_pri\fP set the priority of the new swap area.
|
|
Swap areas with a higher priority are allocated from first.
|
|
If \f4sr_pri\fP 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.
|
|
.PP
|
|
The \f4sr_start\f1 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 \f2getpagesize\f1(2) system call).
|
|
The \f4sr_length\f1, \f4sr_vlength\f1, and
|
|
\f4sr_maxlength\f1 values will be rounded down to the next multiple of the
|
|
system swap page size.
|
|
.PP
|
|
When
|
|
\f4SC_ADD\f1
|
|
or
|
|
\f4SC_REMOVE\f1
|
|
is specified,
|
|
\f2arg\f1
|
|
is a pointer to a
|
|
\f4swapres\f1
|
|
structure containing the following members:
|
|
.PP
|
|
.ft 4
|
|
.nf
|
|
.ta .5i 1.2i 3i
|
|
.sp .5
|
|
char *sr_name; /* pathname of resource */
|
|
off_t sr_start; /* offset to start of swap area */
|
|
off_t sr_length; /* length of swap area */
|
|
.sp .5
|
|
.ft 1
|
|
.fi
|
|
.PP
|
|
\f4sr_start\fP and \f4sr_length\fP are specified in 512-byte blocks.
|
|
.PP
|
|
When
|
|
\f4SC_LIST\f1
|
|
is specified,
|
|
\f2arg\f1
|
|
is a pointer to a
|
|
\f4swaptable\f1
|
|
structure containing the following members:
|
|
.PP
|
|
.ft 4
|
|
.nf
|
|
.ta .5i 2i 3i
|
|
.sp .5
|
|
int swt_n; /* number of swapents following */
|
|
struct swapent swt_ent[]; /* array of swt_n swapents */
|
|
.sp .5
|
|
.ft 1
|
|
.fi
|
|
.PP
|
|
A \f4swapent\f1 structure contains the following members:
|
|
.PP
|
|
.ft 4
|
|
.nf
|
|
.ta .5i 1.7i 3i
|
|
.sp .5
|
|
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 */
|
|
.sp .5
|
|
.ft 1
|
|
.fi
|
|
.PP
|
|
\f4SC_LIST\f1
|
|
causes
|
|
\f4swapctl\f1
|
|
to return at most
|
|
\f4swt_n\f1
|
|
entries.
|
|
The return value of
|
|
\f4swapctl\f1
|
|
is the number actually returned.
|
|
The \f4ST_INDEL\fP bit is turned on in \f4ste_flags\fP if
|
|
the swap file is in the process of being deleted.
|
|
The \f4ST_STALE\fP bit is turned on in \f4ste_flags\fP 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 \f4ST_LOCAL\fP bit is turned on in \f4ste_flags\fP if
|
|
the swap resource resides on a local disk.
|
|
The \f4ST_IOERR\fP bit is turned on in \f4ste_flags\fP 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 \f4ST_EACCES\fP bit is turned on in \f4ste_flags\fP 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 \f4ST_BOOTSWAP\fP bit is turned on in \f4ste_flags\fP if
|
|
this swap device was the initial swap device configured at boot time.
|
|
.PP
|
|
When
|
|
\f4SC_GETNSWP\f1
|
|
is specified,
|
|
\f4swapctl\f1
|
|
returns as its value the number of swap resources in use.
|
|
\f2arg\f1
|
|
is ignored for this operation.
|
|
.PP
|
|
\f4SC_LREMOVE\fP causes
|
|
\f4swapctl\f1
|
|
removes the logical swap resource specified by \f2arg\f1.
|
|
.PP
|
|
When
|
|
\f4SC_GETFREESWAP\fP
|
|
is specified,
|
|
\f4swapctl\f1 copies the number of currently free swap blocks (512 bytes) to the
|
|
address given by \f4arg\fP.
|
|
This is the sum of each swap area's \f4ste_free\fP value,
|
|
converted to 512 byte blocks.
|
|
.PP
|
|
When
|
|
\f4SC_GETSWAPVIRT\fP
|
|
is specified,
|
|
\f4swapctl\f1 copies the total number of virtual swap blocks (512 bytes) to the
|
|
address given by \f4arg\fP.
|
|
This is the sum of each swap area's \f4ste_vpages\fP value, converted
|
|
to 512 byte blocks.
|
|
.PP
|
|
When
|
|
\f4SC_GETRESVSWAP\fP
|
|
is specified,
|
|
\f4swapctl\f1 copies the number of logical swap blocks (512 bytes) that have
|
|
been reserved by all existing processes to the
|
|
address given by \f4arg\fP.
|
|
When this value is greater than the value returned by \f4SC_GETLSWAPTOT\fP
|
|
minus the value returned by \f4SC_SWAPMAX\fP,
|
|
there is the potential for deadlock if every process suddenly requires
|
|
all that it has reserved.
|
|
.PP
|
|
When
|
|
\f4SC_GETLSWAPTOT\fP
|
|
is specified,
|
|
\f4swapctl\f1 copies the current number of logical swap blocks (512 bytes)
|
|
to the address given by \f4arg\fP.
|
|
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.
|
|
.PP
|
|
When
|
|
\f4SC_GETSWAPTOT\fP
|
|
is specified,
|
|
\f4swapctl\f1 copies the current number of physical swap blocks (512 bytes)
|
|
to the address given by \f4arg\fP.
|
|
This is the sum of each swap area's \f4ste_pages\fP value,
|
|
converted to 512 byte blocks.
|
|
.PP
|
|
When
|
|
\f4SC_GETSWAPMAX\fP
|
|
is specified,
|
|
\f4swapctl\f1 copies the maximum number of swap blocks (512 bytes) to the
|
|
address given by \f4arg\fP.
|
|
This is the sum of each swap area's \f4ste_maxpages\fP value,
|
|
converted to 512 byte blocks.
|
|
Since growable swap areas is not yet supported this value will always be
|
|
the same as that returned by \f4SC_GETSWAPTOT\fP.
|
|
.PP
|
|
When specifying
|
|
\f4SC_GETFREESWAP\fP,
|
|
\f4SC_GETSWAPVIRT\fP,
|
|
\f4SC_GETRESVSWAP\fP,
|
|
\f4SC_GETLSWAPTOT\fP,
|
|
\f4SC_GETSWAPTOT\fP, or
|
|
\f4SC_GETSWAPMAX\fP,
|
|
\f4arg\fP should be a pointer to a variable of type \f2off_t\fP.
|
|
.PP
|
|
The \f4SC_SGIADD\f1, \f4SC_ADD\f1, and \f4SC_REMOVE\f1 functions will fail
|
|
if the calling process does not have appropriate privilege.
|
|
.SH RETURN VALUE
|
|
Upon successful completion, the function \f4swapctl\f1 returns
|
|
a value of \f40\f1 for \f4SC_ADD\f1, \f4SC_SGIADD\f1, \f4SC_GETRESVSWAP\fP,
|
|
\f4SC_GETSWAPMAX\fP, \f4SC_GETSWAPVIRT\fP,
|
|
\f4SC_GETFREESWAP\fP, \f4SC_GETSWAPTOT\f1, \f4SC_GETLSWAPTOT\fP,
|
|
or \f4SC_REMOVE\f1,
|
|
the number of \f4struct\f1 \f4swapent\f1 entries actually returned
|
|
for \f4SC_LIST\f1, or
|
|
the number of swap resources in use for \f4SC_GETNSWP\f1.
|
|
Upon failure, the function \f4swapctl\f1 returns a value
|
|
of \f4\-1\f1 and sets \f4errno\f1 to indicate an error.
|
|
.SH ERRORS
|
|
Under the following conditions,
|
|
the function \f4swapctl\f1 fails and sets \f4errno\f1 to:
|
|
.TP 1.25i
|
|
\f4EEXIST\f1
|
|
Part of the range specified by \f4sr_start\fP and \f4sr_length\fP
|
|
is already being used for swapping on the specified resource
|
|
(\f4SC_ADD\f1 or \f4SC_SGIADD\fP).
|
|
.TP
|
|
\f4EFAULT\fP
|
|
.IR arg ,
|
|
\f4sr_name\fP, or \f4ste_path\fP points outside the allocated address space.
|
|
.TP
|
|
\f4EINVAL\f1
|
|
\f4sr_length\fP is not \-1 and either \f4sr_maxlength\fP is not equal to
|
|
\f4sr_length\fP, or \f4sr_vlength\fP is less than
|
|
either \f4sr_length\fP or \f4sr_maxlength\fP.
|
|
.TP
|
|
\f4ENXIO\f1
|
|
The pathname specified for
|
|
\f4SC_ADD\f1 or \f4SC_SGIADD\fP specifies a non-configured block device or
|
|
the block device does not have a \f2size\fP routine.
|
|
.TP
|
|
\f4EINVAL\f1
|
|
\f4sr_pri\fP is not equal to \-1 and it greater than 7.
|
|
.TP
|
|
\f4ENOSPC\f1
|
|
There are no more logical swap devices available (maximum 255)
|
|
(\f4SC_ADD\fP or \f4SC_SGIADD\fP).
|
|
.TP
|
|
\f4EBUSY\f1
|
|
The in-use pages for the swap area to be deleted cannot at this
|
|
time be reclaimed (\f4SC_REMOVE\fP or \f4SC_LREMOVE\fP).
|
|
.TP
|
|
\f4EBUSY\f1
|
|
The specified resource is already in use as a swap area
|
|
(\f4SC_ADD\fP or \f4SC_SGIADD\fP).
|
|
.TP
|
|
\f4EINVAL\f1
|
|
The specified function value is not valid,
|
|
the path specified is not a swap resource (\f4SC_REMOVE\fP),
|
|
part of the range specified by \f4sr_start\fP and \f4sr_length\fP
|
|
lies outside the resource specified (\f4SC_ADD\fP or \f4SC_SGIADD\fP),
|
|
or
|
|
the specified swap area is less than one page (\f4SC_ADD\fP or \f4SC_SGIADD\fP).
|
|
.TP
|
|
\f4EISDIR\f1
|
|
The path specified for
|
|
\f4SC_ADD\f1 or \f4SC_SGIADD\fP
|
|
is a directory.
|
|
.TP
|
|
\f4ELOOP\f1
|
|
Too many symbolic links were encountered in translating the pathname
|
|
provided to
|
|
\f4SC_ADD\f1,
|
|
\f4SC_SGIADD\f1,
|
|
or
|
|
\f4SC_REMOVE\f1 .
|
|
.TP
|
|
\f4ENAMETOOLONG\f1
|
|
The length of a component of the path
|
|
specified for
|
|
\f4SC_ADD\f1,
|
|
\f4SC_SGIADD\f1,
|
|
or
|
|
\f4SC_REMOVE\f1
|
|
exceeds \f4{NAME_MAX}\f1
|
|
characters or the length of the path exceeds \f4{PATH_MAX}\f1 characters
|
|
and \f4{_POSIX_NO_TRUNC}\f1 is in effect.
|
|
.TP
|
|
\f4ENOENT\f1
|
|
The pathname specified for
|
|
\f4SC_ADD\f1,
|
|
\f4SC_SGIADD\f1,
|
|
or
|
|
\f4SC_REMOVE\f1
|
|
does not exist.
|
|
.TP
|
|
\f4ENOMEM\f1
|
|
An insufficient number of
|
|
\f4struct\f1
|
|
\f4swapent\f1
|
|
structures were provided to
|
|
\f4SC_LIST\f1,
|
|
or there were insufficient system storage resources available during an
|
|
\f4SC_ADD\f1,
|
|
\f4SC_SGIADD\f1,
|
|
or
|
|
\f4SC_REMOVE\f1,
|
|
or the system would not have enough swap space after an
|
|
\f4SC_REMOVE\fP.
|
|
.TP
|
|
\f4ENOSYS\fP
|
|
The pathname specified for \f4SC_ADD\fP, \f4SC_SGIADD\fP, or \f4SC_REMOVE\fP is not a file or block special device.
|
|
The file system on which pathname resides does not permit mapping
|
|
or swapping.
|
|
.TP
|
|
\f4ENOTDIR\f1
|
|
Pathname provided to
|
|
\f4SC_ADD\f1,
|
|
\f4SC_SGIADD\f1,
|
|
or
|
|
\f4SC_REMOVE\f1
|
|
contained a component in the path prefix that was not a directory.
|
|
.TP
|
|
\f4EPERM\f1
|
|
The process does not have appropriate privilege.
|
|
.TP
|
|
\f4EROFS\fP
|
|
The pathname specified for \f4SC_ADD\fP or \f4SC_SGIADD\fP
|
|
is a read-only file system.
|
|
.Ee
|