| blob | a26f91f48876c0bf595840ae9bfa396a4d071670 |
1 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .\" Modified by Michael Haardt <michael@moria.de>
6 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
7 .\" Modified 1995-07-22 by Michael Chastain <mec@duracef.shout.net>
8 .\" Modified 1995-07-23 by aeb
9 .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
10 .\" Modified 1998-09-08 by aeb
11 .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com>
12 .\" Modified 2004-10-10 by aeb
13 .\" 2004-12-14 mtk, Anand Kumria: added new errors
14 .\" 2007-06-22 Ivana Varekova <varekova@redhat.com>, mtk
15 .\" Update text describing limit on number of swap files.
16 .\" 2021-01-17 Alex Baranowski <alex@euro-linux.com>
17 .\" Update information about available swap files decreased by
18 .\" CONFIG_DEVICE_PRIVATE option.
19 .\"
20 .\" FIXME Linux 3.11 added SWAP_FLAG_DISCARD_ONCE and SWAP_FLAG_DISCARD_PAGES
21 .\" commit dcf6b7ddd7df8965727746f89c59229b23180e5a
22 .\" Author: Rafael Aquini <aquini@redhat.com>
23 .\" Date: Wed Jul 3 15:02:46 2013 -0700
24 .\"
25 .TH SWAPON 2 2022-09-09 "Linux man-pages (unreleased)"
26 .SH NAME
27 swapon, swapoff \- start/stop swapping to file/device
28 .SH LIBRARY
29 Standard C library
30 .RI ( libc ", " \-lc )
31 .SH SYNOPSIS
32 .nf
33 .B #include <sys/swap.h>
34 .PP
35 .BI "int swapon(const char *" path ", int " swapflags );
36 .BI "int swapoff(const char *" path );
37 .fi
38 .SH DESCRIPTION
39 .BR swapon ()
40 sets the swap area to the file or block device specified by
41 .IR path .
42 .BR swapoff ()
43 stops swapping to the file or block device specified by
44 .IR path .
45 .PP
46 If the
47 .B SWAP_FLAG_PREFER
48 flag is specified in the
49 .BR swapon ()
50 .I swapflags
51 argument, the new swap area will have a higher priority than default.
52 The priority is encoded within
53 .I swapflags
54 as:
55 .PP
56 .in +4n
57 .EX
58 .I "(prio << SWAP_FLAG_PRIO_SHIFT) & SWAP_FLAG_PRIO_MASK"
59 .EE
60 .in
61 .PP
62 If the
63 .B SWAP_FLAG_DISCARD
64 flag is specified in the
65 .BR swapon ()
66 .I swapflags
67 argument, freed swap pages will be discarded before they are reused,
68 if the swap device supports the discard or trim operation.
69 (This may improve performance on some Solid State Devices,
70 but often it does not.)
71 See also NOTES.
72 .PP
73 These functions may be used only by a privileged process (one having the
74 .B CAP_SYS_ADMIN
75 capability).
76 .SS Priority
77 Each swap area has a priority, either high or low.
78 The default priority is low.
79 Within the low-priority areas,
80 newer areas are even lower priority than older areas.
81 .PP
82 All priorities set with
83 .I swapflags
84 are high-priority, higher than default.
85 They may have any nonnegative value chosen by the caller.
86 Higher numbers mean higher priority.
87 .PP
88 Swap pages are allocated from areas in priority order,
89 highest priority first.
90 For areas with different priorities,
91 a higher-priority area is exhausted before using a lower-priority area.
92 If two or more areas have the same priority,
93 and it is the highest priority available,
94 pages are allocated on a round-robin basis between them.
95 .PP
96 As of Linux 1.3.6, the kernel usually follows these rules,
97 but there are exceptions.
98 .SH RETURN VALUE
99 On success, zero is returned.
100 On error, \-1 is returned, and
101 .I errno
102 is set to indicate the error.
103 .SH ERRORS
104 .TP
105 .B EBUSY
106 (for
107 .BR swapon ())
108 The specified
109 .I path
110 is already being used as a swap area.
111 .TP
112 .B EINVAL
113 The file
114 .I path
115 exists, but refers neither to a regular file nor to a block device;
116 .TP
117 .B EINVAL
118 .RB ( swapon ())
119 The indicated path does not contain a valid swap signature or
120 resides on an in-memory filesystem such as
121 .BR tmpfs (5).
122 .TP
123 .BR EINVAL " (since Linux 3.4)"
124 .RB ( swapon ())
125 An invalid flag value was specified in
126 .IR swapflags .
127 .TP
128 .B EINVAL
129 .RB ( swapoff ())
130 .I path
131 is not currently a swap area.
132 .TP
133 .B ENFILE
134 The system-wide limit on the total number of open files has been reached.
135 .TP
136 .B ENOENT
137 The file
138 .I path
139 does not exist.
140 .TP
141 .B ENOMEM
142 The system has insufficient memory to start swapping.
143 .TP
144 .B EPERM
145 The caller does not have the
146 .B CAP_SYS_ADMIN
147 capability.
148 Alternatively, the maximum number of swap files are already in use;
149 see NOTES below.
150 .SH STANDARDS
151 These functions are Linux-specific and should not be used in programs
152 intended to be portable.
153 The second
154 .I swapflags
155 argument was introduced in Linux 1.3.2.
156 .SH NOTES
157 The partition or path must be prepared with
158 .BR mkswap (8).
159 .PP
160 There is an upper limit on the number of swap files that may be used,
161 defined by the kernel constant
162 .BR MAX_SWAPFILES .
163 Before kernel 2.4.10,
164 .B MAX_SWAPFILES
165 has the value 8;
166 since kernel 2.4.10, it has the value 32.
167 Since kernel 2.6.18, the limit is decreased by 2 (thus: 30)
168 if the kernel is built with the
169 .B CONFIG_MIGRATION
170 option
171 (which reserves two swap table entries for the page migration features of
172 .BR mbind (2)
173 and
174 .BR migrate_pages (2)).
175 Since kernel 2.6.32, the limit is further decreased by 1
176 if the kernel is built with the
177 .B CONFIG_MEMORY_FAILURE
178 option.
179 Since kernel 5.14, the limit is further decreased by 4
180 if the kernel is built with the
181 .B CONFIG_DEVICE_PRIVATE
182 option.
183 .PP
184 Discard of swap pages was introduced in kernel 2.6.29,
185 then made conditional
186 on the
187 .B SWAP_FLAG_DISCARD
188 flag in kernel 2.6.36,
189 .\" To be precise: 2.6.35.5
190 which still discards the
191 entire swap area when
192 .BR swapon ()
193 is called, even if that flag bit is not set.
194 .SH SEE ALSO
195 .BR mkswap (8),
196 .BR swapoff (8),
197 .BR swapon (8)