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