swapctl(2)swapctl(2)NAMEswapctl - Manages the system swap space
SYNOPSIS
#include <sys/stat.h> #include <sys/swap.h>
int swapctl(
int cmd,
void *arg );
PARAMETERS
Specifies the operation to be performed. Options include adding a
resource, deleting a resource, removing a resource, or returning the
number of swap resources. Specifies a pointer to a structure. See the
DESCRIPTION section for information on this structure.
DESCRIPTION
The swapctl function manages the system swap space by adding, deleting,
or returning information about swap resources. The cmd parameter that
you select determines the value of the arg parameter. The following
sections discuss the available commands and command arguments.
Available Commands
The swapctl function adds, removes, or returns information on the sys‐
tem swap space using the following values for the cmd parameter:
Includes a new resource in the swap list. Provides a list of the
resources available for swapping. Removes a resource from the swap
list. Counts and returns the number of swap resources
Use this command to determine how many swapent structures will
be needed for a SC_LIST command request
With the exception of the SC_GETSNSWP command, each of these commands
returns information in a structure pointed to by the arg parameter.
The next sections discusses the information that is contained in these
structures after a successful return.
Command Arguments
The value of the arg parameter is specific to the type of command spec‐
ified by the cmd parameter. This section highlights the value for the
arg parameter as it pertains to the commands.
If either the SC_ADD or SC_REMOVE command is specified, the arg parame‐
ter is a pointer to the following swapres structure:
typdef struct swapres {
char sr_name;
off_t sr_start;
off_t sr_length; } swapres_t;
The fields are defined as follows: Provides the pathname of the
resource that is being added or removed. Specifies in 512-byte blocks,
the offset of the resource area from the start. Specifies in 512-byte
blocks, the length of the swap area.
When using the SC_ADD and SC_REMOVE commands, the calling process fails
if the appropriate privileges do not exist for the operation.
If the SC_LIST command is specified, the arg parameter is a pointer to
the following swaptable structure:
int swt_n; struct swapent swt_ent [];
In this structure, the field swt_n specifies the maximum entries that
will be returned by the swapctl function. The swt_ent field is an array
of swt_n swapents. The swapent structure is as follows:
typdef struct swapwent {
char *ste_path;
off_t ste_start;
off_t ste_length;
long ste_pages;
long ste_free;
long ste_flags; } swapwent_t;
Before the swapctl(2) is issued, allocate memory to all of the ste_path
pointers. Ensure that each of the areas allocated is at least MAX‐
PATHLEN bytes long. MAXPATHLEN is defined in <sys/param.h>.
The fields are defined as follows: Specifies the name of the swap file.
Specifies the starting block to begin swapping. Specifies in 512-byte
blocks, the length of the swap area. Specifies the number of pages
available for swapping. Specifies the number of pages that are free.
Sets the ST_INDEL bit if the swap file is being deleted.
RETURN VALUES
On success, the swapctl function returns zero (0) when used with the
SC_ADD or SC_REMOVE commands. For the SC_LIST command, the number of
struct swapent entries actually returned indicates success, and for
SC_GETNSWP, the number of swap resources in use is returned upon suc‐
cess.
On error, the swapctl function returns a value of -1 and sets errno to
indicate the error.
ERRORS
If the swapctl function fails, errno is set to one of the following:
Indicates that the range specified by the sr_start and sr_length fields
for the SC_ADD command is already in use for swapping. Specifies that
the structure pointed to by the arg parameter, or one of the fields
sr_name or ste_path is outside the allocated address space. Specifies
one of the following: The command value is not valid. The path used
with the SC_REMOVE command is not a swap resource. The range indicated
by the sr_start and sr_length fields for the SC_ADD command is outside
the resource specified. The indicated swap area is less than one page
for the SC_ADD command. Indicates that the path used with the SC_ADD
command is not a directory. Indicates that the pathname used with the
SC_ADD or SC_REMOVE commands has too many symbolic links to correctly
translate the pathname. Indicates that the length or path used with
the SC_ADD or SC_REMOVE command exceeds the maximum allowed with
{_POSIX_NO_TRUNC} in effect. Indicates that a nonexisting pathname was
specified with either the SC_ADD or SC_REMOVE commands. Specifies one
of the following: Not enough struct swapent structures exist for the
SC_LIST command. Sufficient system storage resources were not avail‐
able during an SC_ADD or SC_REMOVE operation. Not enough swap space
would exists after an SC_REMOVE operation. Indicates that the pathname
specified for a SC_ADD or SC_REMOVE operation is not a filename or spe‐
cial block device. Specifies that the pathname used with the SC_ADD or
SC_REMOVE commands contained a component in the path that was not a
directory. Indicates that insufficient privileges do not exist for the
operation. Indicates that a read-only file system was specified by the
path for the SC_ADD command.
swapctl(2)
