Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > S

swapctl(2)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

swapctl — manage and configure system swap space

SYNOPSIS

#include <sys/swap.h>

int swapctl(int cmd, void * arg);

PARAMETERS

cmd

Specifies the operation to be performed, which includes: adding a resource, deleting a resource reservation, and listing the swap resources.

SC_ADD

Add a new swap resource to the system.

SC_LIST

List the swap devices on the system. Currently only the primary swap for the next boot will be listed, if it was configured by SC_ADD. See the SC_LIST Command section below for more details.

SC_REMOVE

Remove the swap device configured on the system. Currently only the primary swap for the next boot will be removed. See the SC_REMOVE Command 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 DESCRIPTION below for more information.

DESCRIPTION

The swapctl() 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 successful return.

The SC_ADD Command

For the SC_ADD command, arg parameter is a pointer to the swapres structure with some of the following members, depending on which type of swap is being configured:

swapctl_flags_t sr_flag char * sr_name int64_t sr_start int64_t sr_length int64_t sr_priority int64_t sr_min int64_t sr_lim int64_t sr_res

where the fields are as follows:

sr_flag

is one of the following:

  • SW_PRIMARY | SW_NEXTBOOT (primary swap device for the next boot)

  • SW_DEVICE (swap device for current boot)

  • SW_FILESYS (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 sr_start 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 number of file system blocks that are saved for file system use only.

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 saved for file system use only.

For the SC_ADD command, depending on the sr_flag type, the following members of swapres structure need to be passed in.

SW_PRIMARY | SW_NEXTBOOT:

*sr_name, sr_priority, sr_start, sr_length

SW_DEVICE:

*sr_name, sr_priority, sr_start, sr_length

SW_FILESYS:

*sr_name, sr_priority, sr_min, sr_lim, sr_res

The SW_PRIMARY | SW_NEXTBOOT 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 swchunk kilobytes in size. The length is always rounded down to be a multiple of swchunk.

A VxVM or LVM-based logical volume should be created with contiguous layout to be configured as a primary swap device. For LVM-based systems only the logical volumes within the root volume group can be configured 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 statvfs() call.

The SC_REMOVE Command

For the SC_REMOVE command, arg parameter is a pointer to the swapres structure with the following members:

swapctl_flags_t sr_flag char * sr_name int64_t sr_start int64_t sr_length

where the fields are as follows:

sr_flag

The sr_flag is SW_PRIMARY | SW_NEXTBOOT.

*sr_name

Pathname of the resource that is being removed.

sr_start

Starting offset that was specified with the SC_ADD command.

sr_length

Length of swap device that was specified with the SC_ADD command.

The sr_name, sr_start, and sr_length should be the same values that were used with the SC_ADD command. The sr_flag indicates that the swap resource that is marked as primary swap for the next boot be removed. This will only work if the primary swap device was configured using the SC_ADD command. Devices that have been configured for swap by methods other than swapctl() can not be altered by the SC_REMOVE command.

Swap resources that have been activated for the current boot cannot be removed until the system boot.

When using the SC_ADD and SC_REMOVE commands, the calling process fails if the appropriate privileges do not exist for the operation.

The SC_LIST Command

For the SC_LIST command, arg parameter is a pointer to the swaptable structure with following members:

int swt_n swapctl_flags_t swt_flag struct swapent swt_ent []

where:

swt_n

Specifies the maximum entries that will be returned by swapctl().

swt_ent

Is an array of swt_n swapents. Currently the SC_LIST command can be used to list the primary swap configured for next boot, so the array size for the swapent structures is 1.

swt_flag

sr_flag is SW_PRIMARY | SW_NEXTBOOT.

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 SC_ADD command. Devices that have been configured for use by methods other than swapctl() can not be listed by the SC_LIST command.

The swapent structure will return the information in the following fields:

char *ste_path nt64_t ste_start nt64_t ste_length ev_t ste_dev

Before swapctl() is issued, allocate memory to all of the ste_path pointers. Ensure that each of the areas allocated is at least MAXPATHLEN bytes long. MAXPATHLEN is defined in <sys/param.h>.

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 SC_LIST command for now only lists the primary swap device that is configured for next boot. The pstst_getswap() interface has to be used to get the list of all other swap resources.

RETURN VALUES

On success, the swapctl() system call returns 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.

On error, the swapctl() system call returns a value of -1 and sets errno to indicate the error.

ERRORS

If the swapctl() system call fails, errno is set to one of the following:

EACCES

A component of the sr_name prefix denies search permission.

EACCES

The input device pointer to be sr_name has a logical volume on it.

EALREADY

For SC_ADD, the device associated with sr_name already has swap turned on.

EBUSY

The device associated with sr_name is already in use.

EEXIST

For primary swap configuration, indicates that a swap device is already configured as primary swap for next boot. It should be removed using the SC_REMOVE command before a new one can be added.

EIO

Unable to read the device associated with sr_name.

EIO

Unable to read or write to the kernel registry services (see krs(5)).

EFAULT

Specifies that the structure pointed to by the arg parameter or swt_ent field of swaptable_t struct, or one of the fields sr_name or ste_path is outside the allocated address space.

EINVAL

Invalid input parameter passed in.

EINVAL

Indicates that the LVM device passed in for SC_ADD is not early boot accessible or is a non-contiguous logical volume

EINVAL

The path used with the SC_REMOVE command is not a swap resource.

EINVAL

The range indicated by the sr_start and sr_length fields for the SC_ADD command is outside the resource specified.

ELOOP

Indicates that the pathname used with the SC_ADD or SC_REMOVE commands has too many symbolic links to correctly translate the pathname.

ENAMETOOLONG

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.

ENOENT

Indicates that a invalid pathname was specified with either the SC_ADD or SC_REMOVE commands.

ENOENT

Indicates that the primary swap was not set using the SC_ADD command when using with the SC_LIST command to list primary swap.

ENOTBLK

Indicates that the path used with the SC_ADD command for adding device swap is not a block device file.

ENOTDIR

Indicates that the path used with the SC_ADD command for adding file system swap is not a directory.

ENXIO

The device associated with sr_name could not be opened.

EPERM

Indicates that insufficient privileges do not exist for the operation.

EROFS

Indicates that a read-only file system was specified by the path for the SC_ADD 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/dsk/c4t3d0 "; 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 swapctl() is used for configuring primary swap, other methods for configuring primary swap like lvlnboot, vxvmboot, 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 primary swap using swapctl(), then other device(s) that are configured for primary swap using the above mentioned methods will not be effective.

The lvlnboot, vxvmboot, and system configuration file methods for configuring swap are deprecated and will be obsoleted in future releases.

AUTHOR

swapctl() was developed by HP.

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.