]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da MK |
24 | .\" |
25 | .\" Modified by Michael Haardt <michael@moria.de> | |
26 | .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> | |
27 | .\" Modified 1995-07-22 by Michael Chastain <mec@duracef.shout.net> | |
28 | .\" Modified 1995-07-23 by aeb | |
29 | .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com> | |
30 | .\" Modified 1998-09-08 by aeb | |
c11b1abf | 31 | .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 32 | .\" Modified 2004-10-10 by aeb |
526f4e1f | 33 | .\" 2004-12-14 mtk, Anand Kumria: added new errors |
4db7cf5d MK |
34 | .\" 2007-06-22 Ivana Varekova <varekova@redhat.com>, mtk |
35 | .\" Update text describing limit on number of swap files. | |
fea681da | 36 | .\" |
9bbf6fbf MK |
37 | .\" FIXME Linux 3.11 added SWAP_FLAG_DISCARD_ONCE and SWAP_FLAG_DISCARD_PAGES |
38 | .\" commit dcf6b7ddd7df8965727746f89c59229b23180e5a | |
39 | .\" Author: Rafael Aquini <aquini@redhat.com> | |
40 | .\" Date: Wed Jul 3 15:02:46 2013 -0700 | |
41 | .\" | |
4b8c67d9 | 42 | .TH SWAPON 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da MK |
43 | .SH NAME |
44 | swapon, swapoff \- start/stop swapping to file/device | |
45 | .SH SYNOPSIS | |
46 | .B #include <unistd.h> | |
47 | .br | |
fea681da | 48 | .B #include <sys/swap.h> |
68e4db0a | 49 | .PP |
fea681da MK |
50 | .BI "int swapon(const char *" path ", int " swapflags ); |
51 | .br | |
52 | .BI "int swapoff(const char *" path ); | |
53 | .SH DESCRIPTION | |
526f4e1f | 54 | .BR swapon () |
fea681da MK |
55 | sets the swap area to the file or block device specified by |
56 | .IR path . | |
526f4e1f | 57 | .BR swapoff () |
fea681da MK |
58 | stops swapping to the file or block device specified by |
59 | .IR path . | |
60 | .PP | |
bd5d3c1c HD |
61 | If the |
62 | .B SWAP_FLAG_PREFER | |
63 | flag is specified in the | |
526f4e1f | 64 | .BR swapon () |
fea681da | 65 | .I swapflags |
bd5d3c1c | 66 | argument, the new swap area will have a higher priority than default. |
526f4e1f MK |
67 | The priority is encoded within |
68 | .I swapflags | |
69 | as: | |
ba39b288 MK |
70 | .PP |
71 | .in +4n | |
72 | .EX | |
73 | .I "(prio << SWAP_FLAG_PRIO_SHIFT) & SWAP_FLAG_PRIO_MASK" | |
74 | .EE | |
75 | .in | |
fea681da | 76 | .PP |
bd5d3c1c HD |
77 | If the |
78 | .B SWAP_FLAG_DISCARD | |
79 | flag is specified in the | |
80 | .BR swapon () | |
81 | .I swapflags | |
eb67e713 | 82 | argument, freed swap pages will be discarded before they are reused, |
bd5d3c1c HD |
83 | if the swap device supports the discard or trim operation. |
84 | (This may improve performance on some Solid State Devices, | |
85 | but often it does not.) | |
86 | See also NOTES. | |
87 | .PP | |
33a0ccb2 | 88 | These functions may be used only by a privileged process (one having the |
fea681da MK |
89 | .B CAP_SYS_ADMIN |
90 | capability). | |
ffc78e2c | 91 | .SS Priority |
fea681da MK |
92 | Each swap area has a priority, either high or low. |
93 | The default priority is low. | |
94 | Within the low-priority areas, | |
95 | newer areas are even lower priority than older areas. | |
96 | .PP | |
97 | All priorities set with | |
98 | .I swapflags | |
99 | are high-priority, higher than default. | |
2fda57bd | 100 | They may have any nonnegative value chosen by the caller. |
fea681da MK |
101 | Higher numbers mean higher priority. |
102 | .PP | |
103 | Swap pages are allocated from areas in priority order, | |
104 | highest priority first. | |
105 | For areas with different priorities, | |
106 | a higher-priority area is exhausted before using a lower-priority area. | |
107 | If two or more areas have the same priority, | |
108 | and it is the highest priority available, | |
109 | pages are allocated on a round-robin basis between them. | |
110 | .PP | |
111 | As of Linux 1.3.6, the kernel usually follows these rules, | |
112 | but there are exceptions. | |
47297adb | 113 | .SH RETURN VALUE |
c13182ef MK |
114 | On success, zero is returned. |
115 | On error, \-1 is returned, and | |
fea681da MK |
116 | .I errno |
117 | is set appropriately. | |
118 | .SH ERRORS | |
119 | .TP | |
e28334ce | 120 | .B EBUSY |
c13182ef | 121 | (for |
58d323a7 | 122 | .BR swapon ()) |
e28334ce MK |
123 | The specified |
124 | .I path | |
125 | is already being used as a swap area. | |
126 | .TP | |
fea681da MK |
127 | .B EINVAL |
128 | The file | |
129 | .I path | |
e28334ce | 130 | exists, but refers neither to a regular file nor to a block device; |
2424abac MK |
131 | .TP |
132 | .B EINVAL | |
133 | .RB ( swapon ()) | |
134 | The indicated path does not contain a valid swap signature or | |
4e07c70f MK |
135 | resides on an in-memory filesystem such as |
136 | .BR tmpfs (5). | |
2424abac | 137 | .TP |
81c096f2 MK |
138 | .BR EINVAL " (since Linux 3.4)" |
139 | .RB ( swapon ()) | |
140 | An invalid flag value was specified in | |
141 | .IR flags . | |
142 | .TP | |
2424abac MK |
143 | .B EINVAL |
144 | .RB ( swapoff ()) | |
526f4e1f MK |
145 | .I path |
146 | is not currently a swap area. | |
fea681da MK |
147 | .TP |
148 | .B ENFILE | |
e258766b | 149 | The system-wide limit on the total number of open files has been reached. |
fea681da MK |
150 | .TP |
151 | .B ENOENT | |
152 | The file | |
c13182ef | 153 | .I path |
fea681da MK |
154 | does not exist. |
155 | .TP | |
156 | .B ENOMEM | |
157 | The system has insufficient memory to start swapping. | |
158 | .TP | |
159 | .B EPERM | |
160 | The caller does not have the | |
161 | .B CAP_SYS_ADMIN | |
988db661 | 162 | capability. |
4db7cf5d MK |
163 | Alternatively, the maximum number of swap files are already in use; |
164 | see NOTES below. | |
47297adb | 165 | .SH CONFORMING TO |
8382f16d | 166 | These functions are Linux-specific and should not be used in programs |
fea681da | 167 | intended to be portable. |
526f4e1f MK |
168 | The second |
169 | .I swapflags | |
170 | argument was introduced in Linux 1.3.2. | |
fea681da MK |
171 | .SH NOTES |
172 | The partition or path must be prepared with | |
173 | .BR mkswap (8). | |
efeece04 | 174 | .PP |
4db7cf5d | 175 | There is an upper limit on the number of swap files that may be used, |
891e1629 MK |
176 | defined by the kernel constant |
177 | .BR MAX_SWAPFILES . | |
ec774e61 | 178 | Before kernel 2.4.10, |
891e1629 MK |
179 | .B MAX_SWAPFILES |
180 | has the value 8; | |
ec774e61 | 181 | since kernel 2.4.10, it has the value 32. |
4db7cf5d | 182 | Since kernel 2.6.18, the limit is decreased by 2 (thus: 30) |
2f0af33b MK |
183 | if the kernel is built with the |
184 | .B CONFIG_MIGRATION | |
185 | option | |
4db7cf5d MK |
186 | (which reserves two swap table entries for the page migration features of |
187 | .BR mbind (2) | |
188 | and | |
189 | .BR migrate_pages (2)). | |
d71593a9 IHV |
190 | Since kernel 2.6.32, the limit is further decreased by 1 |
191 | if the kernel is built with the | |
192 | .B CONFIG_MEMORY_FAILURE | |
193 | option. | |
efeece04 | 194 | .PP |
bd5d3c1c HD |
195 | Discard of swap pages was introduced in kernel 2.6.29, |
196 | then made conditional | |
197 | on the | |
198 | .B SWAP_FLAG_DISCARD | |
199 | flag in kernel 2.6.36, | |
200 | .\" To be precise: 2.6.35.5 | |
201 | which still discards the | |
202 | entire swap area when | |
203 | .BR swapon () | |
204 | is called, even if that flag bit is not set. | |
47297adb | 205 | .SH SEE ALSO |
fea681da MK |
206 | .BR mkswap (8), |
207 | .BR swapoff (8), | |
208 | .BR swapon (8) |