swapctl(2)swapctl(2)NAMEswapctl - manage and configure system swap space
SYNOPSISPARAMETERS
cmd Specifies the operation to be performed, which includes:
adding a resource, deleting a resource reservation, and list‐
ing the swap resources.
Add a new swap resource to the system.
List the swap devices on the system.
Currently only the primary swap for the next
boot will be listed, if it was configured by
See the section below for more details.
Remove the swap device configured on the system.
Currently the file system swap removal is not
supported. See the section below for more
details.
arg Specifies a pointer to a structure and is dependent on the
type of command specified by the cmd parameter. See below
for more information.
DESCRIPTION
The system call manages system swap space by adding or deleting swap
resources or returning information about swap resources. The cmd
parameter determines the value of the arg parameter.
Each of these commands accepts/returns information in a structure
pointed to by the arg parameter. The following sections discuss the
information that should be passed in to the system call. They also
explain the information contained in these structures after a success‐
ful return.
The SC_ADD Command
For the command, arg parameter is a pointer to the structure with some
of the following members, depending on which type of swap is being con‐
figured:
where the fields are as follows:
sr_flag is one of the following:
· (primary swap device for the next boot)
· (swap device for current boot)
· (swap file system for the current boot)
See the flag field description below for details
on the usage.
*sr_name Provides the pathname of the resource that is
being added.
sr_start Specifies, in 1 kilobyte blocks, the starting
offset of the swap resource area.
sr_length Specifies, in 1 kilobyte blocks, the length of
the swap area. Value of 0 means configure the
entire device, starting from the offset.
sr_priority Indicates the order in which the swap space from
the device or file system is used. It has a
range of 0 (highest) to 10 (lowest). Swap space
is taken from the lower-numbered systems first.
sr_min (Needed for file system swap only.) Indicates
the minimum number of file system blocks the swap
system will take from the file system.
sr_lim (Needed for file system swap only.) Indicates
the maximum number of file system blocks the swap
system is allowed to take from the file system.
sr_res (Needed for file system swap only.) Indicates
the number of file system blocks that are
reserved for swap system use only.
For the command, depending on the sr_flag type, the following members
of structure need to be passed in.
The flag is used to change the primary swap configuration for the next
boot. This change will only take place after the next boot. The
changed configuration will remain effective until it is changed again
using this option.
The sr_priority for the primary swap for the next boot should always be
set to 1. Other priority values are considered invalid.
A value of -1 for sr_start implies a presence of a file system on the
swap device and swap area to start immediately after that.
The length of the device swap to be configured should at least be kilo‐
bytes in size. The length is always rounded down to be a multiple of
A VxVM or LVM-based logical volume should be created with contiguous
layout to be configured as a primary swap device. For LVM-based sys‐
tems only the logical volumes within the root volume group can be con‐
figured as a primary swap device.
For a pre-existing directory swap, a value of -1 for sr_min, sr_lim,
sr_res, or sr_priority will keep the value unchanged. This can be used
to change selective values without affecting others. For example, if
priority of a pre-existing directory swap needs to be changed without
affecting the values of sr_min, sr_lim, or sr_res, one can specify the
new priority value and pass -1 for other arguments.
The size for the file system blocks mentioned above is the preferred
file system block size. The preferred file system block size can be
obtained by the call.
The SC_REMOVE Command
For the command, arg parameter is a pointer to the structure with the
following members:
where the fields are as follows:
sr_flag is one of the following:
· (primary swap device for the next boot)
· (swap device for current boot)
*sr_name Pathname of the resource that is being removed.
sr_start Starting offset that was specified with the com‐
mand.
sr_length Length of swap device that was specified with the
command.
The sr_name, sr_start, and sr_length should be the same values that
were used with the command. The for the next boot primary swap will
only work if the primary swap device was configured using the command.
A primary swap device that has been configured for swap by methods
other than can not be altered by the command.
When using the and commands, the calling process fails if the appropri‐
ate privileges do not exist for the operation.
The SC_LIST Command
For the command, arg parameter is a pointer to the structure with fol‐
lowing members:
where:
swt_n Specifies the maximum entries that will be
returned by
swt_ent Is an array of swt_n Currently the command can be
used to list the primary swap configured for next
boot, so the array size for the structures is 1.
swt_flag sr_flag is
The flag indicates that the swap resource that is
marked as swap for the next boot be listed. This
will only work if the primary swap device was
configured using the command. Devices that have
been configured for use by methods other than can
not be listed by the command.
The structure will return the information in the following fields:
Before is issued, allocate memory to all of the ste_path pointers.
Ensure that each of the areas allocated is at least bytes long. is
defined in
The fields are defined as follows:
*ste_path Specifies the name of the swap device.
ste_dev Specifies the device number corresponding to the
ste_path.
ste_priority Specifies the priority at which the device was
configured.
ste_start Specifies in 512-byte blocks, the starting block
to begin swapping.
ste_length Specifies in 512-byte blocks, the length of the
swap area.
ste_dev Specifies the device number corresponding to the
ste_path.
The command for now only lists the primary swap device that is config‐
ured for next boot. The interface has to be used to get the list of
all other swap resources.
RETURN VALUES
On success, the system call returns 0 when used with the or commands.
For the command, the number of entries actually returned indicates suc‐
cess.
On error, the system call returns a value of -1 and sets to indicate
the error.
ERRORS
If the system call fails, is set to one of the following:
A component of the
sr_name prefix denies search permission.
The input device pointer to be
sr_name has a logical volume on it.
For the device associated with sr_name already has
swap turned on.
The device associated with
sr_name is already in use.
For primary swap configuration, indicates that a swap device is
already configured as primary swap for next boot.
It should be removed using the command before a
new one can be added.
Unable to read the device associated with
sr_name.
Unable to read or write to the kernel registry services (see
krs(5)).
Specifies that the structure pointed to by the
arg parameter or swt_ent field of struct, or one
of the fields sr_name or ste_path is outside the
allocated address space.
Invalid input parameter passed in.
Indicates that the LVM device passed in for
is not early boot accessible or is a non-contigu‐
ous logical volume
The path used with the
command is not a swap resource.
The range indicated by the
sr_start and sr_length fields for the command is
outside the resource specified.
Indicates that the pathname used with the
or commands has too many symbolic links to cor‐
rectly translate the pathname.
Indicates that the length or path used with the
or command exceeds the maximum allowed with in
effect.
Indicates that a invalid pathname was specified with either the
or commands.
Indicates that the primary swap was not set using the
command when using with the command to list pri‐
mary swap.
Indicates that the path used with the
command for adding device swap is not a block
device file.
Indicates that the path used with the
command for adding file system swap is not a
directory.
The device associated with
sr_name could not be opened.
Indicates that insufficient privileges do not exist for the
operation.
Indicates that a read-only file system was specified by the path
for the
command.
EXAMPLES
The following example adds, lists and removes a primary swap device for
next boot:
#include <sys/swap.h>
#include <stdio.h>
int main() {
int rv;
swapres_t swp;
swaptable_t swt;
swapent_t swent;
char path[1024] = "/dev/disk/disk12 ";
char ret_path[1024];
bzero(ret_path, 1024);
/* add a new primary swap for next boot */
swp.sr_flag = SW_PRIMARY | SW_NEXTBOOT;
swp.sr_name = path;
swp.sr_start = 0;
swp.sr_length = 0; /* 0 len implies, use the entire dev */
swp.sr_priority = 1;
rv = swapctl(SC_ADD, (void *)&swp);
if (rv) {
perror("swapctl/SC_ADD failed");
exit(1);
}
/* list the swap device configured above */
swent.ste_path = path;
swt.swt_n = 1;
swt.swt_flags = SW_PRIMARY | SW_NEXTBOOT;
swt.swt_ent = &swent;
rv = swapctl(SC_LIST, (void *)&swt);
if (rv != 1) { /* returns the number of swap devices returned */
printf("swapctl/SC_LIST returned: %d \n", rv);
perror("swapctl/SC_LIST failed");
exit(2);
}
printf("Primary swap for next boot: %s \n", swent.ste_path);
/* Remove the above configured primary swap */
swp.sr_flag = SW_PRIMARY | SW_NEXTBOOT;
swp.sr_name = path; /* same path as used for SC_ADD */
swp.sr_start = 0; /* same start as used for SC_ADD */
swp.sr_length = 0; /* same length as used for SC_ADD */
swp.sr_priority = 1;
rv = swapctl(SC_REMOVE, (void *)&swp);
if (rv) {
perror("swapctl/SC_REMOVE failed");
exit(3);
}
return 0;
}
WARNINGS
If is used for configuring primary swap, other methods for configuring
primary swap like and system configuration files (see lvlnboot(1M),
vxvmboot(1M), and system(4)), and PA HP-UX boot loader mechanism will
become ineffective. In other words, if a device is configured for pri‐
mary swap using then other device(s) that are configured for primary
swap using the above mentioned methods will not be effective.
The and system configuration file methods for configuring swap are dep‐
recated and will be obsoleted in future releases.
AUTHOR
was developed by HP.
SEE ALSOhpux(1M), lvlnboot(1M), vxvmboot(1M), swapctl(2), system(4),
swchunk(5).
swapctl(2)