1.\" $NetBSD: swapctl.2,v 1.10 1998/08/29 17:11:09 mrg Exp $ 2.\" 3.\" Copyright (c) 1997 Matthew R. Green 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.Dd June 20, 1997 36.Dt SWAPCTL 2 37.Os 38.Sh NAME 39.Nm swapctl 40.Nd modify swap configuration 41.Sh SYNOPSIS 42.Fd #include <unistd.h> 43.Fd #include <sys/swap.h> 44.Ft int 45.Fn swapctl "int cmd" "const void *arg" "int misc" 46.Sh DESCRIPTION 47The 48.Fn swapctl 49function is used to add and delete swap devices, and modify their 50configuration. 51.Pp 52The 53.Fa cmd 54parameter specifies the operation to be performed. 55The 56.Fa arg 57and 58.Fa misc 59parameters have different meanings, depending on the 60.Fa cmd 61parameter. 62.Bl -item -offset indent 63.It 64If 65.Fa cmd 66is 67.Dv SWAP_NSWAP , 68the current number of swap devices in the system is returned. 69The 70.Fa arg 71and 72.Fa misc 73parameters are ignored. 74.It 75If 76.Fa cmd 77is 78.Dv SWAP_STATS , 79the current statistics for swap devices are returned in the 80.Fa arg 81parameter. 82No more than 83.Fa misc 84swap devices are returned. 85The 86.Fa arg 87parameter should point to an array of at least 88.Fa misc 89struct swapent structures: 90.Bd -literal 91struct swapent { 92 dev_t se_dev; /* device id */ 93 int se_flags; /* entry flags */ 94 int se_nblks; /* total blocks */ 95 int se_inuse; /* blocks in use */ 96 int se_priority; /* priority */ 97 char se_path[MAXPATHLEN]; /* path to entry */ 98}; 99.Ed 100.Pp 101The flags are defined as 102.Bd -literal 103 SWF_INUSE in use: we have swapped here 104 SWF_ENABLE enabled: we can swap here 105 SWF_BUSY busy: I/O happening here 106 SWF_FAKE fake: still being built 107.Ed 108.It 109If 110.Fa cmd 111is 112.Dv SWAP_ON , 113the 114.Fa arg 115parameter is used as a pathname of a file to enable swapping to. 116The 117.Fa misc 118parameter is used to set the priority of this swap device. 119.It 120If 121.Fa cmd 122is 123.Dv SWAP_OFF , 124the 125.Fa arg 126parameter is used as the pathname of a file to disable swapping from. 127The 128.Fa misc 129parameter is ignored. 130.It 131If 132.Fa cmd 133is 134.Dv SWAP_CTL , 135the 136.Fa arg 137and 138.Fa misc 139parameters have the same function as for the 140.Dv SWAP_ON 141case, except that they change the priority of a currently enabled swap device. 142.El 143.Pp 144When swapping is enabled on a block device, the first portion of the disk is 145left unused to prevent any disklabel present from being overwritten. 146This space is allocated from the swap device when the 147.Dv SWAP_ON 148command is used. 149.Sh RETURN VALUES 150If the 151.Fa cmd 152parameter is 153.Dv SWAP_NSWAP 154or 155.Dv SWAP_STATS , 156.Fn swapctl 157returns the number of swap devices, if successful. 158The 159.Dv SWAP_NSWAP 160command is always successful. 161Otherwise it returns 0 on success and \-1 on failure, 162setting the global variable 163.Va errno 164to indicate the error. 165.Sh ERRORS 166.Fn swapctl 167succeeds unless: 168.Bl -tag -width Er 169.It Bq Er ENOTDIR 170A component of the path prefix is not a directory. 171.It Bq Er ENAMETOOLONG 172A component of a pathname exceeded 173.Dv NAME_MAX 174characters, or an entire path name exceeded 175.Dv PATH_MAX 176characters. 177.It Bq Er ENOENT 178The named device does not exist. 179For the 180.Dv SWAP_CTL 181command, the named device is not currently enabled for swapping. 182.It Bq Er EACCES 183Search permission is denied for a component of the path prefix. 184.It Bq Er ELOOP 185Too many symbolic links were encountered in translating the pathname. 186.It Bq Er EPERM 187The caller is not the superuser. 188.It Bq Er EBUSY 189The device specified by 190.Fa arg 191has already been made available for swapping. 192.It Bq Er EINVAL 193The device configured by 194.Fa arg 195has no associated size, or the 196.Fa cmd 197was unknown. 198.It Bq Er ENXIO 199The major device number of 200.Fa arg 201is out of range (this indicates no device driver exists 202for the associated hardware). 203.It Bq Er EIO 204An I/O error occurred while opening the swap device. 205.It Bq Er EFAULT 206.Fa arg 207points outside the process' allocated address space. 208.El 209.Sh SEE ALSO 210.Xr config 8 , 211.Xr swapctl 8 212.Sh BUGS 213The 214.Dv SWAP_OFF 215command is currently unimplemented by the 216.Ox 217kernel. 218.Sh AUTHORS 219The current swap system was designed and implemented by Matthew Green 220<mrg@eterna.com.au>, with help from Paul Kranenburg <pk@NetBSD.ORG> 221and Leo Weppelman <leo@NetBSD.ORG>, and insights from Jason R. Thorpe 222<thorpej@NetBSD.ORG>. 223.Sh HISTORY 224The 225.Fn swapctl 226function call appeared in 227.Nx 1.3 . 228The 229.Fa se_path 230member was added to 231.Li struct swapent 232in 233.Nx 1.4 , 234when the header file was also moved from 235.Aq Pa vm/vm_swap.h . 236