May 29, 2005 SWAPCTL 2

### NAME

swapctl - modify swap configuration

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

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

### DESCRIPTION

The swapctl function is used to add and delete swap devices, and modify their configuration.

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+1];    /* 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

  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.

  If ```cmd` is ```SWAP_DUMPDEV`, the ```arg` parameter is used as the pathname of a device to use as the dump device, should the system panic.

  If ```cmd` is ```SWAP_GETDUMPDEV`, the ```arg` parameter points to a dev_t, which is filled in by the current dump 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.

The priority of a swap device can be used to fill faster swap devices before slower ones. A priority of 0 is the highest, with larger numbers having lower priority. For a fuller discussion on swap priority, see the SWAP PRIORITY section in swapctl(8).

### 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 path name exceeded ```PATH_MAX` characters.

[```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 super-user.

[```EBUSY`]
  The device specified by ```arg` has already been made available for swapping.

[```EINVAL`]
  The device configured by ```arg` has no associated 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).

[```ENXIO`]
  The block device specified by ```arg` is not marked as a swap partition in the disklabel.

[```EIO`]
  An I/O error occurred while opening the swap device.

[```EFAULT`]
  ```arg` points outside the process' allocated address space.

### SEE ALSO

swapctl(8)

### HISTORY

The swapctl(``) function call appeared in NetBSD1.3. The ```se_path` member was added to struct swapent in NetBSD1.4, when the header file was also moved from <```vm/vm_swap.h`> to its current location in <```sys/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>.