]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
3 | .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 | |
4 | .\" | |
5 | .\" Permission is granted to make and distribute verbatim copies of this | |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
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 | .\" |
4db7cf5d | 37 | .TH SWAPON 2 2007-06-22 "Linux" "Linux Programmer's Manual" |
fea681da MK |
38 | .SH NAME |
39 | swapon, swapoff \- start/stop swapping to file/device | |
40 | .SH SYNOPSIS | |
41 | .B #include <unistd.h> | |
42 | .br | |
43 | .B #include <asm/page.h> /* to find PAGE_SIZE */ | |
44 | .br | |
45 | .B #include <sys/swap.h> | |
46 | .sp | |
47 | .BI "int swapon(const char *" path ", int " swapflags ); | |
48 | .br | |
49 | .BI "int swapoff(const char *" path ); | |
50 | .SH DESCRIPTION | |
526f4e1f | 51 | .BR swapon () |
fea681da MK |
52 | sets the swap area to the file or block device specified by |
53 | .IR path . | |
526f4e1f | 54 | .BR swapoff () |
fea681da MK |
55 | stops swapping to the file or block device specified by |
56 | .IR path . | |
57 | .PP | |
526f4e1f | 58 | .BR swapon () |
fea681da MK |
59 | takes a |
60 | .I swapflags | |
61 | argument. | |
62 | If | |
63 | .I swapflags | |
64 | has the | |
7b2b5ea4 | 65 | .B SWAP_FLAG_PREFER |
fea681da | 66 | bit turned on, the new swap area will have a higher priority than default. |
526f4e1f MK |
67 | The priority is encoded within |
68 | .I swapflags | |
69 | as: | |
fea681da MK |
70 | .br |
71 | .sp | |
72 | .I " (prio << SWAP_FLAG_PRIO_SHIFT) & SWAP_FLAG_PRIO_MASK" | |
73 | .br | |
74 | .PP | |
75 | These functions may only be used by a privileged process (one having the | |
76 | .B CAP_SYS_ADMIN | |
77 | capability). | |
ffc78e2c | 78 | .SS Priority |
fea681da MK |
79 | Each swap area has a priority, either high or low. |
80 | The default priority is low. | |
81 | Within the low-priority areas, | |
82 | newer areas are even lower priority than older areas. | |
83 | .PP | |
84 | All priorities set with | |
85 | .I swapflags | |
86 | are high-priority, higher than default. | |
87 | They may have any non-negative value chosen by the caller. | |
88 | Higher numbers mean higher priority. | |
89 | .PP | |
90 | Swap pages are allocated from areas in priority order, | |
91 | highest priority first. | |
92 | For areas with different priorities, | |
93 | a higher-priority area is exhausted before using a lower-priority area. | |
94 | If two or more areas have the same priority, | |
95 | and it is the highest priority available, | |
96 | pages are allocated on a round-robin basis between them. | |
97 | .PP | |
98 | As of Linux 1.3.6, the kernel usually follows these rules, | |
99 | but there are exceptions. | |
100 | .SH "RETURN VALUE" | |
c13182ef MK |
101 | On success, zero is returned. |
102 | On error, \-1 is returned, and | |
fea681da MK |
103 | .I errno |
104 | is set appropriately. | |
105 | .SH ERRORS | |
106 | .TP | |
e28334ce | 107 | .B EBUSY |
c13182ef | 108 | (for |
58d323a7 | 109 | .BR swapon ()) |
e28334ce MK |
110 | The specified |
111 | .I path | |
112 | is already being used as a swap area. | |
113 | .TP | |
fea681da MK |
114 | .B EINVAL |
115 | The file | |
116 | .I path | |
e28334ce | 117 | exists, but refers neither to a regular file nor to a block device; |
526f4e1f MK |
118 | or, for |
119 | .BR swapon (), | |
4ae67b7d MK |
120 | the indicated path does not contain a valid swap signature or |
121 | resides on an in-memory filesystem like tmpfs; or, for | |
526f4e1f MK |
122 | .BR swapoff (), |
123 | .I path | |
124 | is not currently a swap area. | |
fea681da MK |
125 | .TP |
126 | .B ENFILE | |
127 | The system limit on the total number of open files has been reached. | |
128 | .TP | |
129 | .B ENOENT | |
130 | The file | |
c13182ef | 131 | .I path |
fea681da MK |
132 | does not exist. |
133 | .TP | |
134 | .B ENOMEM | |
135 | The system has insufficient memory to start swapping. | |
136 | .TP | |
137 | .B EPERM | |
138 | The caller does not have the | |
139 | .B CAP_SYS_ADMIN | |
988db661 | 140 | capability. |
4db7cf5d MK |
141 | Alternatively, the maximum number of swap files are already in use; |
142 | see NOTES below. | |
fea681da MK |
143 | .SH "CONFORMING TO" |
144 | These functions are Linux specific and should not be used in programs | |
145 | intended to be portable. | |
526f4e1f MK |
146 | The second |
147 | .I swapflags | |
148 | argument was introduced in Linux 1.3.2. | |
fea681da MK |
149 | .SH NOTES |
150 | The partition or path must be prepared with | |
151 | .BR mkswap (8). | |
4db7cf5d MK |
152 | |
153 | There is an upper limit on the number of swap files that may be used, | |
2f0af33b | 154 | defined by the kernel constant MAX_SWAPFILES. |
4db7cf5d MK |
155 | Before kernel 2.6.10, MAX_SWAPFILES has the value 8; |
156 | since kernel 2.6.10, it has the value 32. | |
157 | Since kernel 2.6.18, the limit is decreased by 2 (thus: 30) | |
2f0af33b MK |
158 | if the kernel is built with the |
159 | .B CONFIG_MIGRATION | |
160 | option | |
4db7cf5d MK |
161 | (which reserves two swap table entries for the page migration features of |
162 | .BR mbind (2) | |
163 | and | |
164 | .BR migrate_pages (2)). | |
fea681da MK |
165 | .SH "SEE ALSO" |
166 | .BR mkswap (8), | |
167 | .BR swapoff (8), | |
168 | .BR swapon (8) |