SWAPCTL(2) | System Calls Manual | SWAPCTL(2)

# NAME

`swapctl` — modify swap configuration

# SYNOPSIS

`#include <sys/types.h>`
`#include <sys/swap.h>`
`#include <unistd.h>`

int
`swapctl`(int cmd, const void *arg, int misc);

# DESCRIPTION

The `swapctl`() function is used to add and delete swap devices, modify their configuration or query their statistics.

The cmd parameter specifies the operation to be performed. The arg and misc parameters have different meanings, depending on the cmd parameter.

- If cmd is `SWAP_NSWAP`, the current number of swap devices in the system is returned. The arg and misc parameters are ignored.
- If cmd is `SWAP_STATS`, the current statistics for swap devices are returned in the arg parameter. No more than misc swap devices are returned. The arg parameter should point to an array of at least misc struct swapent structures:

      struct swapent {
      	dev_t	se_dev;			/* device id */
      	int	se_flags;		/* entry flags */
      	int	se_nblks;		/* total blocks */
      	int	se_inuse;		/* blocks in use */
      	int	se_priority;		/* priority */
      	char	se_path[PATH_MAX];	/* path to entry */
      };

  The flags are defined as

      	SWF_INUSE	in use: we have swapped here
      	SWF_ENABLE	enabled: we can swap here
      	SWF_BUSY	busy: I/O happening here
      	SWF_FAKE	fake: still being built

  All but `SWAP_NSWAP` and `SWAP_STATS` require superuser privileges.

- If cmd is `SWAP_ON`, the arg parameter is used as a pathname of a file to enable swapping to. The misc parameter is used to set the priority of this swap device.
- If cmd is `SWAP_OFF`, the arg parameter is used as the pathname of a file to disable swapping from. The misc parameter is ignored.
- If cmd is `SWAP_CTL`, the arg and misc parameters have the same function as for the `SWAP_ON` case, except that they change the priority of a currently enabled swap device.

When swapping is enabled on a block device, the first portion of the disk is left unused to prevent any disklabel present from being overwritten. This space is allocated from the swap device when the `SWAP_ON` command is used.

# RETURN VALUES

If the cmd parameter is `SWAP_NSWAP` or `SWAP_STATS`, `swapctl`() returns the number of swap devices, if successful. The `SWAP_NSWAP` command is always successful. Otherwise it returns 0 on success and -1 on failure, setting the global variable errno to indicate the error.

# ERRORS

`swapctl`() succeeds unless:

[`ENOTDIR`]
  A component of the path prefix is not a directory.
[`ENAMETOOLONG`]
  A component of a pathname exceeded `NAME_MAX` characters, or an entire pathname (including the terminating NUL) exceeded `PATH_MAX` bytes.
[`ENOENT`]
  The named device does not exist. For the `SWAP_CTL` command, the named device is not currently enabled for swapping.
[`EACCES`]
  Search permission is denied for a component of the path prefix.
[`ELOOP`]
  Too many symbolic links were encountered in translating the pathname.
[`EPERM`]
  The caller is not the superuser.
[`EBUSY`]
  The device specified by arg has already been made available for swapping.
[`EINVAL`]
  The device configured by arg has insufficient size, or the cmd was unknown.
[`ENXIO`]
  The major device number of arg is out of range (this indicates no device driver exists for the associated hardware).
[`EIO`]
  An I/O error occurred while opening the swap device.
[`EFAULT`]
  arg points outside the process' allocated address space.
[`ENOTSUP`]
  The device specified by arg cannot be used for swapping.

# SEE ALSO

config(8), swapctl(8)

# HISTORY

The `swapctl`() function call appeared in NetBSD 1.3. The se_path member was added to struct swapent in NetBSD 1.4, when the header file was also moved from `<vm/vm_swap.h>`.

# AUTHORS

The current swap system was designed and implemented by Matthew Green <mrg@eterna.com.au>, with help from Paul Kranenburg <pk@NetBSD.ORG> and Leo Weppelman <leo@NetBSD.ORG>, and insights from Jason R. Thorpe <thorpej@NetBSD.ORG>.

June 24, 2024 | Debian