NAME

swapctl − Manages the system swap space

SYNOPSIS

#include <sys/stat.h>
#include <sys/swap.h> int swapctl(
        int cmd,
        void ∗arg );

PARAMETERS

cmdSpecifies the operation to be performed.  Options include adding a resource, deleting a resource, removing a resource, or returning the number of swap resources. 

argSpecifies 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 system swap space using the following values for the cmd parameter:

SC_ADD
Includes a new resource in the swap list.

SC_LIST
Provides a list of the resources available for swapping.

SC_REMOVE
Removes a resource from the swap list.

SC_GETNSWP
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 specified 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 parameter 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:

∗sr_name
Provides the pathname of the resource that is being added or removed.

sr_start
Specifies in 512-byte blocks, the offset of the resource area from the start.

sr_length
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 MAXPATHLEN bytes long.  MAXPATHLEN is defined in <sys/param.h>. 

The fields are defined as follows:

∗ste_path
Specifies the name of the swap file.

ste_start
Specifies the starting block to begin swapping.

ste_length
Specifies in 512-byte blocks, the length of the swap area.

ste_page
Specifies the number of pages available for swapping.

ste_free
Specifies the number of pages that are free.

ste_flags
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 success. 

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:

[EEXIST]
Indicates that the range specified by the sr_start and sr_length fields for the SC_ADD command is already in use for swapping. 

[EFAULT]
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. 

[EINVAL]
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. 

[EISDIR]
Indicates that the path used with the SC_ADD command is not a directory. 

[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 nonexisting pathname was specified with either the SC_ADD or SC_REMOVE commands. 

[ENOMEM]
Specifies one of the following:

       •Not enough struct swapent structures exist for the SC_LIST command. 

       •Sufficient system storage resources were not available during an SC_ADD or SC_REMOVE operation. 

       •Not enough swap space would exists after an SC_REMOVE operation. 

[ENOSYS]
Indicates that the pathname specified for a SC_ADD or SC_REMOVE operation is not a filename or special block device. 

[ENOTDIR]
Specifies that the pathname used with the SC_ADD or SC_REMOVE commands contained a component in the path that was not a directory. 

[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.