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