From 2989e9f477bd30350056aa6e488718d9acbd26a3 Mon Sep 17 00:00:00 2001 From: mrg Date: Fri, 20 Jun 1997 05:47:58 +0000 Subject: [PATCH] actually document swapctl(2). --- lib/libc/sys/swapctl.2 | 161 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 151 insertions(+), 10 deletions(-) diff --git a/lib/libc/sys/swapctl.2 b/lib/libc/sys/swapctl.2 index 61f77cd7552a..cf3e5442c62d 100644 --- a/lib/libc/sys/swapctl.2 +++ b/lib/libc/sys/swapctl.2 @@ -1,5 +1,6 @@ -.\" $NetBSD: swapctl.2,v 1.2 1997/06/12 22:39:17 mrg Exp $ +.\" $NetBSD: swapctl.2,v 1.3 1997/06/20 05:47:58 mrg Exp $ .\" +.\" Copyright (c) 1997 Matthew R. Green .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -31,9 +32,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" from: @(#)swapon.2 8.1 (Berkeley) 6/4/93 -.\" -.Dd June 12, 1997 +.Dd June 20, 1997 .Dt SWAPON 2 .Os NetBSD .Sh NAME @@ -48,22 +47,164 @@ .Sh DESCRIPTION The .Nm -function is used to add swap devices, and modify their configuration. +function is used to add and delete swap devices, and modify their configuration. The .Nm swapon function only exists as as backwards compatibility feature until the next major bump of the .Pa libc major from 12. It should never be used in new code, and should be -removed form existed code. +removed from existed code. +.Pp +The +.Fa cmd +parameter specifies the operation to be performed. THe +.Fa arg +and +.Fa misc +parameters have different meanings, depending on the +.Fa cmd +parameter. +.Bl -item -offset indent +.It +If +.Fa cmd +is +.Dv SWAP_NSWAP , +the current number of swap devices in the system is returned. The +.Fa arg +and +.Fa misc +parameters are ignored. +.It +If +.Fa cmd +is +.Dv SWAP_STATS , +the current statistics for swap devices are returned in the +.Fa arg +parameter. No more than +.Fa misc +swap devices are returned. The +.Fa arg +parameter should point to an array of at least +.Fa misc +struct swapent structures: +.Bd -literal +struct swapent { + dev_t se_dev; + int se_flags; + int se_nblks; + int se_inuse; + int se_priority; +}; +.Ed +.It +If +.Fa cmd +is +.Dv SWAP_ON , +the +.Fa arg +parameter is used as a pathname of a file to enable swapping to. +The +.Fa misc +parameter is used to set the priority of this swap device. +.It +If +.Fa cmd +is +.Dv SWAP_OFF , +the +.Fa arg +parameter is used as the pathname of a file to disable swapping from. +The +.Fa misc +parameter is ignored. +.It +If +.Fa cmd +is +.Dv SWAP_CTL , +the +.Fa arg +and +.Fa misc +parameters have the same function as for the +.Dv SWAP_ON +case, except that they change the priority of a currently enable swap device. +.El +.Sh RETURN VALUES +If the +.Fa cmd +parameter is +.Dv SWAP_NSTATS +or +.Dv SWAP_STATS , +.Fn swapctl +returns the number of swap devices, if successful. The +.Dv SWAP_NSTATS +command is always successful. Otherwise it returns 0 on success and -1 +on failure, setting the global variable +.Va errno +to indicate the error. +.Sh ERRORS +.Fn swapctl +succeeds unless: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded +.Dv NAME_MAX +characters, or an entire path name exceeded +.Dv PATH_MAX +characters. +.It Bq Er ENOENT +The named device does not exist. For the +.Dv SWAP_CTL +command, the named device is not currently enabled for swapping. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The caller is not the super-user. +.It Bq Er EBUSY +The device specified by +.Fa arg +has already +been made available for swapping +.It Bq Er EINVAL +The device configured by +.Fa arg +has no associated size, or the +.Fa cmd +was unknown. +.It Bq Er ENXIO +The major device number of +.Fa arg +is out of range (this indicates no device driver exists +for the associated hardware). +.It Bq Er EIO +An I/O error occurred while opening the swap device. +.It Bq Er EFAULT +.Fa arg +points outside the process's allocated address space. .Sh SEE ALSO .Xr swapctl 8 , .Xr config 8 .Sh BUGS -There is no way to stop swapping on a disk so that the pack may be -dismounted. -.Pp -This call will be upgraded in future versions of the system. +The +.Dv SWAP_OFF +command is currently unimplemented by the +.Nx +kernel. +.Sh AUTHOR +The current swap system was designed and implemented by Matthew Green +, with help from Paul Kranenburg +and Leo Weppelman , and insights from Jason R. Thorpe +. .Sh HISTORY The .Fn swapctl