xref: /netbsd/lib/libc/sys/swapctl.2 (revision bf9ec67e) 
1.\"	$NetBSD: swapctl.2,v 1.23 2002/02/08 01:28:22 ross 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 LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.Fd #include \*[Lt]unistd.h\*[Gt]
45.Fd #include \*[Lt]sys/swap.h\*[Gt]
46.Ft int
47.Fn swapctl "int cmd" "const void *arg" "int misc"
48.Sh DESCRIPTION
49The
50.Nm
51function is used to add and delete swap devices, and modify their
52configuration.
53.Pp
54The
55.Fa cmd
56parameter specifies the operation to be performed.  The
57.Fa arg
58and
59.Fa misc
60parameters have different meanings, depending on the
61.Fa cmd
62parameter.
63.Bl -item -offset indent
64.It
65If
66.Fa cmd
67is
68.Dv SWAP_NSWAP ,
69the current number of swap devices in the system is returned.  The
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.  No more than
82.Fa misc
83swap devices are returned.  The
84.Fa arg
85parameter should point to an array of at least
86.Fa misc
87struct swapent structures:
88.Bd -literal
89struct swapent {
90	dev_t	se_dev;			/* device id */
91	int	se_flags;		/* entry flags */
92	int	se_nblks;		/* total blocks */
93	int	se_inuse;		/* blocks in use */
94	int	se_priority;		/* priority */
95	char	se_path[PATH_MAX+1];	/* path to entry */
96};
97.Ed
98.Pp
99The flags are defined as
100.Bd -literal
101	SWF_INUSE       in use: we have swapped here
102	SWF_ENABLE      enabled: we can swap here
103	SWF_BUSY        busy: I/O happening here
104	SWF_FAKE        fake: still being built
105.Ed
106.It
107If
108.Fa cmd
109is
110.Dv SWAP_ON ,
111the
112.Fa arg
113parameter is used as a pathname of a file to enable swapping to.
114The
115.Fa misc
116parameter is used to set the priority of this swap device.
117.It
118If
119.Fa cmd
120is
121.Dv SWAP_OFF ,
122the
123.Fa arg
124parameter is used as the pathname of a file to disable swapping from.
125The
126.Fa misc
127parameter is ignored.
128.It
129If
130.Fa cmd
131is
132.Dv SWAP_CTL ,
133the
134.Fa arg
135and
136.Fa misc
137parameters have the same function as for the
138.Dv SWAP_ON
139case, except that they change the priority of a currently enabled swap device.
140.It
141If
142.Fa cmd
143is
144.Dv SWAP_DUMPDEV ,
145the
146.Fa arg
147parameter is used as the pathname of a device to use as the dump device,
148should the system panic.
149.It
150If
151.Fa cmd
152is
153.Dv SWAP_GETDUMPDEV ,
154the
155.Fa arg
156parameter points to a dev_t, which is filled in by the current dump device.
157.El
158.Pp
159When swapping is enabled on a block device, the first portion of the disk is
160left unused to prevent any disklabel present from being overwritten.  This
161space is allocated from the swap device when the
162.Dv SWAP_ON
163command is used.
164.Pp
165The priority of a swap device can be used to fill faster swap devices before
166slower ones.  A priority of 0 is the highest, with larger numbers having
167lower priority.  For a fuller discussion on swap priority, see the
168.Sx SWAP PRIORITY
169section in
170.Xr swapctl 8 .
171.Sh RETURN VALUES
172If the
173.Fa cmd
174parameter is
175.Dv SWAP_NSWAP
176or
177.Dv SWAP_STATS ,
178.Fn swapctl
179returns the number of swap devices, if successful.  The
180.Dv SWAP_NSWAP
181command is always successful.  Otherwise it returns 0 on success and -1
182on failure, setting the global variable
183.Va errno
184to indicate the error.
185.Sh ERRORS
186.Fn swapctl
187succeeds unless:
188.Bl -tag -width Er
189.It Bq Er ENOTDIR
190A component of the path prefix is not a directory.
191.It Bq Er ENAMETOOLONG
192A component of a pathname exceeded
193.Dv NAME_MAX
194characters, or an entire path name exceeded
195.Dv PATH_MAX
196characters.
197.It Bq Er ENOENT
198The named device does not exist.  For the
199.Dv SWAP_CTL
200command, the named device is not currently enabled for swapping.
201.It Bq Er EACCES
202Search permission is denied for a component of the path prefix.
203.It Bq Er ELOOP
204Too many symbolic links were encountered in translating the pathname.
205.It Bq Er EPERM
206The caller is not the super-user.
207.It Bq Er EBUSY
208The device specified by
209.Fa arg
210has already been made available for swapping.
211.It Bq Er EINVAL
212The device configured by
213.Fa arg
214has no associated size, or the
215.Fa cmd
216was unknown.
217.It Bq Er ENXIO
218The major device number of
219.Fa arg
220is out of range (this indicates no device driver exists
221for the associated hardware).
222.It Bq Er EIO
223An I/O error occurred while opening the swap device.
224.It Bq Er EFAULT
225.Fa arg
226points outside the process' allocated address space.
227.El
228.Sh SEE ALSO
229.Xr swapctl 8
230.Sh HISTORY
231The
232.Fn swapctl
233function call appeared in
234.Nx 1.3 .
235The
236.Fa se_path
237member was added to
238.Va struct swapent
239in
240.Nx 1.4 ,
241when the header file was also moved from
242.Pa \*[Lt]vm/vm_swap.h\*[Gt] ,
243to its current location in
244.Pa \*[Lt]sys/swap.h\*[Gt] .
245.Sh AUTHORS
246The current swap system was designed and implemented by Matthew Green
247\*[Lt]mrg@eterna.com.au\*[Gt], with help from Paul Kranenburg \*[Lt]pk@NetBSD.ORG\*[Gt]
248and Leo Weppelman \*[Lt]leo@NetBSD.ORG\*[Gt], and insights from Jason R. Thorpe
249\*[Lt]thorpej@NetBSD.ORG\*[Gt].
250