| blob | 7c6234400a0de835ee2478c1fabf6bc71eacb78c |
1 .\" $NetBSD: swapctl.2,v 1.37 2010/05/31 12:16:20 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
68 The
69 .Nm
70 function is used to add and delete swap devices, and modify their
71 configuration.
72 .Pp
73 The
74 .Fa cmd
75 parameter specifies the operation to be performed.
76 The
77 .Fa arg
78 and
79 .Fa misc
80 parameters have different meanings, depending on the
81 .Fa cmd
82 parameter.
83 .Bl -enum -offset indent
84 .It
85 If
86 .Fa cmd
87 is
88 .Dv SWAP_NSWAP ,
89 the current number of swap devices in the system is returned.
90 The
91 .Fa arg
92 and
93 .Fa misc
94 parameters are ignored.
95 .It
96 If
97 .Fa cmd
98 is
99 .Dv SWAP_STATS ,
100 the current statistics for swap devices are returned in the
101 .Fa arg
102 parameter.
103 No more than
104 .Fa misc
105 swap devices are returned.
106 The
107 .Fa arg
108 parameter should point to an array of at least
109 .Fa misc
110 struct swapent structures:
111 .Bd -literal
112 struct 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
122 The 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
130 If
131 .Fa cmd
132 is
133 .Dv SWAP_ON ,
134 the
135 .Fa arg
136 parameter is used as a pathname of a file to enable swapping to.
137 The
138 .Fa misc
139 parameter is used to set the priority of this swap device.
140 .It
141 If
142 .Fa cmd
143 is
144 .Dv SWAP_OFF ,
145 the
146 .Fa arg
147 parameter is used as the pathname of a file to disable swapping from.
148 The
149 .Fa misc
150 parameter is ignored.
151 .It
152 If
153 .Fa cmd
154 is
155 .Dv SWAP_CTL ,
156 the
157 .Fa arg
158 and
159 .Fa misc
160 parameters have the same function as for the
161 .Dv SWAP_ON
162 case, except that they change the priority of a currently enabled swap device.
163 .It
164 If
165 .Fa cmd
166 is
167 .Dv SWAP_DUMPDEV ,
168 the
169 .Fa arg
170 parameter is used as the pathname of a device to use as the dump device,
171 should the system panic.
172 .It
173 If
174 .Fa cmd
175 is
176 .Dv SWAP_GETDUMPDEV ,
177 the
178 .Fa arg
179 parameter points to a dev_t, which is filled in by the current dump device.
180 .El
181 .Pp
182 When swapping is enabled on a block device, the first portion of the disk is
183 left unused to prevent any disklabel present from being overwritten.
184 This space is allocated from the swap device when the
185 .Dv SWAP_ON
186 command is used.
187 .Pp
188 The priority of a swap device can be used to fill faster swap devices before
189 slower ones.
190 A priority of 0 is the highest, with larger numbers having lower priority.
191 For a fuller discussion on swap priority, see the
192 .Sx SWAP PRIORITY
193 section in
194 .Xr swapctl 8 .
195 .Sh RETURN VALUES
196 If the
197 .Fa cmd
198 parameter is
199 .Dv SWAP_NSWAP
200 or
201 .Dv SWAP_STATS ,
202 .Fn swapctl
203 returns the number of swap devices, if successful.
204 The
205 .Dv SWAP_NSWAP
206 command is always successful.
207 Otherwise it returns 0 on success and \-1
208 on failure, setting the global variable
209 .Va errno
210 to indicate the error.
211 .Sh ERRORS
212 .Fn swapctl
213 succeeds unless:
214 .Bl -tag -width Er
215 .It Bq Er ENOTDIR
216 A component of the path prefix is not a directory.
217 .It Bq Er ENAMETOOLONG
218 A component of a pathname exceeded
219 .Brq Dv NAME_MAX
220 characters, or an entire path name exceeded
221 .Brq Dv PATH_MAX
222 characters.
223 .It Bq Er ENOENT
224 The named device does not exist.
225 For the
226 .Dv SWAP_CTL
227 command, the named device is not currently enabled for swapping.
228 .It Bq Er EACCES
229 Search permission is denied for a component of the path prefix.
230 .It Bq Er ELOOP
231 Too many symbolic links were encountered in translating the pathname.
232 .It Bq Er EPERM
233 The caller is not the super-user.
234 .It Bq Er EBUSY
235 The device specified by
236 .Fa arg
237 has already been made available for swapping.
238 .It Bq Er EINVAL
239 The device configured by
240 .Fa arg
241 has no associated size, or the
242 .Fa cmd
243 was unknown.
244 .It Bq Er ENXIO
245 The major device number of
246 .Fa arg
247 is out of range (this indicates no device driver exists
248 for the associated hardware).
249 .It Bq Er ENXIO
250 The block device specified by
251 .Fa arg
252 is not marked as a swap partition in the disklabel.
253 .It Bq Er EIO
254 An I/O error occurred while opening the swap device.
255 .It Bq Er EFAULT
256 .Fa arg
257 points outside the process' allocated address space.
258 .El
259 .Sh SEE ALSO
260 .Xr swapctl 8
261 .Sh HISTORY
262 The
263 .Fn swapctl
264 function call appeared in
265 .Nx 1.3 .
266 The
267 .Fa se_path
268 member was added to
269 .Va struct swapent
270 in
271 .Nx 1.4 ,
272 when the header file was also moved from
273 .In vm/vm_swap.h
274 to its current location in
275 .In sys/swap.h .
276 .Sh AUTHORS
277 The current swap system was designed and implemented by
278 Matthew Green
279 .Aq mrg@eterna.com.au ,
280 with help from Paul Kranenburg
281 .Aq pk@NetBSD.org
282 and Leo Weppelman
283 .Aq leo@NetBSD.org ,
284 and insights from Jason R. Thorpe
285 .Aq thorpej@NetBSD.org .