]>
Commit | Line | Data |
---|---|---|
8e85a9cc | 1 | .\" Copyright 2002 Urs Thuermann (urs@isnogud.escape.de) |
482ee361 | 2 | .\" and Copyright 2015 Michael Kerrisk <mtk.manpages@gmail.com> |
8e85a9cc MK |
3 | .\" |
4 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) | |
5 | .\" This is free documentation; you can redistribute it and/or | |
6 | .\" modify it under the terms of the GNU General Public License as | |
7 | .\" published by the Free Software Foundation; either version 2 of | |
8 | .\" the License, or (at your option) any later version. | |
9 | .\" | |
10 | .\" The GNU General Public License's references to "object code" | |
11 | .\" and "executables" are to be interpreted as the output of any | |
12 | .\" document formatting or typesetting system, including | |
13 | .\" intermediate and printed output. | |
14 | .\" | |
15 | .\" This manual is distributed in the hope that it will be useful, | |
16 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
18 | .\" GNU General Public License for more details. | |
19 | .\" | |
20 | .\" You should have received a copy of the GNU General Public | |
21 | .\" License along with this manual; if not, write to the Free | |
22 | .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, | |
23 | .\" USA. | |
24 | .\" %%%LICENSE_END | |
25 | .\" | |
6b621d05 | 26 | .TH LOOP 4 2020-02-09 "Linux" "Linux Programmer's Manual" |
8e85a9cc | 27 | .SH NAME |
482ee361 | 28 | loop, loop-control \- loop devices |
8e85a9cc MK |
29 | .SH SYNOPSIS |
30 | #include <linux/loop.h> | |
31 | .SH DESCRIPTION | |
32 | The loop device is a block device that maps its data blocks not to a | |
33 | physical device such as a hard disk or optical disk drive, | |
34 | but to the blocks of | |
35 | a regular file in a filesystem or to another block device. | |
36 | This can be useful for example to provide a block device for a filesystem | |
37 | image stored in a file, so that it can be mounted with the | |
38 | .BR mount (8) | |
39 | command. | |
40 | You could do | |
a2b7a144 MK |
41 | .PP |
42 | .in +4n | |
43 | .EX | |
8e85a9cc MK |
44 | $ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP |
45 | $ \fBsudo losetup /dev/loop4 file.img \fP | |
46 | $ \fBsudo mkfs -t ext4 /dev/loop4\fP | |
47 | $ \fBsudo mkdir /myloopdev\fP | |
48 | $ \fBsudo mount /dev/loop4 /myloopdev\fP | |
a2b7a144 MK |
49 | .EE |
50 | .in | |
dd3568a1 | 51 | .PP |
8e85a9cc MK |
52 | See |
53 | .BR losetup (8) | |
54 | for another example. | |
5b539973 | 55 | .PP |
8e85a9cc MK |
56 | A transfer function can be specified for each loop device for |
57 | encryption and decryption purposes. | |
5b539973 | 58 | .PP |
8e85a9cc MK |
59 | The following |
60 | .BR ioctl (2) | |
61 | operations are provided by the loop block device: | |
62 | .TP | |
63 | .B LOOP_SET_FD | |
64 | Associate the loop device with the open file whose file descriptor is | |
65 | passed as the (third) | |
66 | .BR ioctl (2) | |
67 | argument. | |
68 | .TP | |
69 | .B LOOP_CLR_FD | |
70 | Disassociate the loop device from any file descriptor. | |
71 | .TP | |
72 | .B LOOP_SET_STATUS | |
73 | Set the status of the loop device using the (third) | |
74 | .BR ioctl (2) | |
75 | argument. | |
76 | This argument is a pointer to | |
77 | .I loop_info | |
78 | structure, defined in | |
79 | .I <linux/loop.h> | |
80 | as: | |
5b539973 | 81 | .IP |
8e85a9cc | 82 | .in +4n |
b8302363 | 83 | .EX |
8e85a9cc | 84 | struct loop_info { |
ff1cac76 MK |
85 | int lo_number; /* ioctl r/o */ |
86 | dev_t lo_device; /* ioctl r/o */ | |
87 | unsigned long lo_inode; /* ioctl r/o */ | |
88 | dev_t lo_rdevice; /* ioctl r/o */ | |
8e85a9cc MK |
89 | int lo_offset; |
90 | int lo_encrypt_type; | |
91 | int lo_encrypt_key_size; /* ioctl w/o */ | |
2b38639a MK |
92 | int lo_flags; /* ioctl r/w (r/o before |
93 | Linux 2.6.25) */ | |
8e85a9cc MK |
94 | char lo_name[LO_NAME_SIZE]; |
95 | unsigned char lo_encrypt_key[LO_KEY_SIZE]; | |
ff1cac76 | 96 | /* ioctl w/o */ |
8e85a9cc MK |
97 | unsigned long lo_init[2]; |
98 | char reserved[4]; | |
99 | }; | |
b8302363 | 100 | .EE |
e646a1ba | 101 | .in |
5b539973 | 102 | .IP |
5cb4874e MK |
103 | The encryption type |
104 | .RI ( lo_encrypt_type ) | |
105 | should be one of | |
8e85a9cc MK |
106 | .BR LO_CRYPT_NONE , |
107 | .BR LO_CRYPT_XOR , | |
108 | .BR LO_CRYPT_DES , | |
109 | .BR LO_CRYPT_FISH2 , | |
110 | .BR LO_CRYPT_BLOW , | |
111 | .BR LO_CRYPT_CAST128 , | |
112 | .BR LO_CRYPT_IDEA , | |
113 | .BR LO_CRYPT_DUMMY , | |
114 | .BR LO_CRYPT_SKIPJACK , | |
115 | or (since Linux 2.6.0) | |
116 | .BR LO_CRYPT_CRYPTOAPI . | |
5b539973 | 117 | .IP |
56b4a66a MK |
118 | The |
119 | .I lo_flags | |
120 | field is a bit mask that can include zero or more of the following: | |
121 | .RS | |
122 | .TP | |
123 | .BR LO_FLAGS_READ_ONLY | |
124 | The loopback device is read-only. | |
125 | .TP | |
126 | .BR LO_FLAGS_AUTOCLEAR " (since Linux 2.6.25)" | |
127 | .\" commit 96c5865559cee0f9cbc5173f3c949f6ce3525581 | |
128 | The loopback device will autodestruct on last close. | |
129 | .TP | |
130 | .BR LO_FLAGS_PARTSCAN " (since Linux 3.2)" | |
131 | .\" commit e03c8dd14915fabc101aa495828d58598dc5af98 | |
132 | Allow automatic partition scanning. | |
133 | .RE | |
8e85a9cc MK |
134 | .TP |
135 | .B LOOP_GET_STATUS | |
136 | Get the status of the loop device. | |
137 | The (third) | |
138 | .BR ioctl (2) | |
139 | argument must be a pointer to a | |
140 | .IR "struct loop_info" . | |
5210b796 | 141 | .TP |
14ae756a MK |
142 | .BR LOOP_CHANGE_FD " (since Linux 2.6.5)" |
143 | Switch the backing store of the loop device to the new file identified | |
144 | file descriptor specified in the (third) | |
145 | .BR ioctl (2) | |
146 | argument, which is an integer. | |
147 | This operation is possible only if the loop device is read-only and | |
148 | the new backing store is the same size and type as the old backing store. | |
149 | .TP | |
5210b796 MK |
150 | .BR LOOP_SET_CAPACITY " (since Linux 2.6.30)" |
151 | .\" commit 53d6660836f233df66490707365ab177e5fb2bb4 | |
152 | Resize a live loop device. | |
153 | One can change the size of the underlying backing store and then use this | |
154 | operation so that the loop driver learns about the new size. | |
155 | This operation takes no argument. | |
9d40af2a YX |
156 | .TP |
157 | .BR LOOP_SET_DIRECT_IO " (since Linux 4.10)" | |
158 | .\" commit ab1cb278bc7027663adbfb0b81404f8398437e11 | |
f7eff3e7 MK |
159 | Set DIRECT I/O mode on the loop device, so that |
160 | it can be used to open backing file. | |
38ad8652 | 161 | The (third) |
eb39881d | 162 | .BR ioctl (2) |
38ad8652 | 163 | argument is an unsigned long value. |
f7eff3e7 | 164 | A non-zero represents direct I/O mode. |
89593f2d YX |
165 | .TP |
166 | .BR LOOP_SET_BLOCK_SIZE " (since Linux 4.14)" | |
167 | .\" commit 89e4fdecb51cf5535867026274bc97de9480ade5 | |
38ad8652 MK |
168 | Set the block size of the loop device. |
169 | The (third) | |
eb39881d | 170 | .BR ioctl (2) |
38ad8652 | 171 | argument is an unsigned long value. |
f7eff3e7 MK |
172 | This value must be a power of two in the range |
173 | [512,pagesize]; | |
174 | otherwise, an | |
175 | .B EINVAL | |
176 | error results. | |
8e85a9cc MK |
177 | .PP |
178 | Since Linux 2.6, there are two new | |
179 | .BR ioctl (2) | |
180 | operations: | |
181 | .TP | |
182 | .BR LOOP_SET_STATUS64 ", " LOOP_GET_STATUS64 | |
183 | These are similar to | |
184 | .BR LOOP_SET_STATUS " and " LOOP_GET_STATUS | |
185 | described above but use the | |
186 | .I loop_info64 | |
187 | structure, | |
188 | which has some additional fields and a larger range for some other fields: | |
5b539973 | 189 | .IP |
8e85a9cc | 190 | .in +4n |
b8302363 | 191 | .EX |
8e85a9cc | 192 | struct loop_info64 { |
ff1cac76 MK |
193 | uint64_t lo_device; /* ioctl r/o */ |
194 | uint64_t lo_inode; /* ioctl r/o */ | |
195 | uint64_t lo_rdevice; /* ioctl r/o */ | |
8e85a9cc | 196 | uint64_t lo_offset; |
ff1cac76 MK |
197 | uint64_t lo_sizelimit; /* bytes, 0 == max available */ |
198 | uint32_t lo_number; /* ioctl r/o */ | |
8e85a9cc | 199 | uint32_t lo_encrypt_type; |
ff1cac76 | 200 | uint32_t lo_encrypt_key_size; /* ioctl w/o */ |
2b38639a MK |
201 | uint32_t lo_flags; i /* ioctl r/w (r/o before |
202 | Linux 2.6.25) */ | |
8e85a9cc MK |
203 | uint8_t lo_file_name[LO_NAME_SIZE]; |
204 | uint8_t lo_crypt_name[LO_NAME_SIZE]; | |
205 | uint8_t lo_encrypt_key[LO_KEY_SIZE]; /* ioctl w/o */ | |
206 | uint64_t lo_init[2]; | |
207 | }; | |
b8302363 | 208 | .EE |
e646a1ba | 209 | .in |
482ee361 MK |
210 | .SS /dev/loop-control |
211 | Since Linux 3.1, | |
212 | .\" commit 770fe30a46a12b6fb6b63fbe1737654d28e84844 | |
213 | the kernel provides the | |
214 | .I /dev/loop-control | |
215 | device, which permits an application to dynamically find a free device, | |
216 | and to add and remove loop devices from the system. | |
217 | To perform these operations, one first opens | |
218 | .IR /dev/loop-control | |
219 | and then employs one of the following | |
220 | .BR ioctl (2) | |
221 | operations: | |
222 | .TP | |
223 | .B LOOP_CTL_GET_FREE | |
224 | Allocate or find a free loop device for use. | |
225 | On success, the device number is returned as the result of the call. | |
226 | This operation takes no argument. | |
227 | .TP | |
228 | .B LOOP_CTL_ADD | |
229 | Add the new loop device whose device number is specified | |
230 | as a long integer in the third | |
231 | .BR ioctl (2) | |
232 | argument. | |
233 | On success, the device index is returned as the result of the call. | |
234 | If the device is already allocated, the call fails with the error | |
235 | .BR EEXIST . | |
236 | .TP | |
237 | .B LOOP_CTL_REMOVE | |
238 | Remove the loop device whose device number is specified | |
239 | as a long integer in the third | |
240 | .BR ioctl (2) | |
241 | argument. | |
242 | On success, the device number is returned as the result of the call. | |
243 | If the device is in use, the call fails with the error | |
244 | .BR EBUSY . | |
69f351b0 | 245 | .SH FILES |
991f7440 MK |
246 | .TP |
247 | .IR /dev/loop* | |
248 | The loop block special device files. | |
a14af333 | 249 | .SH EXAMPLES |
1a7f3370 MK |
250 | The program below uses the |
251 | .I /dev/loop-control | |
252 | device to find a free loop device, opens the loop device, | |
253 | opens a file to be used as the underlying storage for the device, | |
254 | and then associates the loop device with the backing store. | |
255 | The following shell session demonstrates the use of the program: | |
5b539973 | 256 | .PP |
1a7f3370 | 257 | .in +4n |
b8302363 | 258 | .EX |
1a7f3370 MK |
259 | $ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP |
260 | 10+0 records in | |
261 | 10+0 records out | |
262 | 10485760 bytes (10 MB) copied, 0.00609385 s, 1.7 GB/s | |
263 | $ \fBsudo ./mnt_loop file.img\fP | |
264 | loopname = /dev/loop5 | |
b8302363 | 265 | .EE |
e646a1ba | 266 | .in |
1a7f3370 MK |
267 | .SS Program source |
268 | \& | |
e7d0bb47 | 269 | .EX |
1a7f3370 MK |
270 | #include <fcntl.h> |
271 | #include <linux/loop.h> | |
272 | #include <sys/ioctl.h> | |
273 | #include <stdio.h> | |
274 | #include <stdlib.h> | |
275 | #include <unistd.h> | |
276 | ||
d1a71985 | 277 | #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e |
1a7f3370 MK |
278 | } while (0) |
279 | ||
280 | int | |
281 | main(int argc, char *argv[]) | |
282 | { | |
283 | int loopctlfd, loopfd, backingfile; | |
284 | long devnr; | |
285 | char loopname[4096]; | |
286 | ||
287 | if (argc != 2) { | |
d1a71985 | 288 | fprintf(stderr, "Usage: %s backing\-file\en", argv[0]); |
1a7f3370 MK |
289 | exit(EXIT_FAILURE); |
290 | } | |
291 | ||
292 | loopctlfd = open("/dev/loop\-control", O_RDWR); | |
293 | if (loopctlfd == \-1) | |
294 | errExit("open: /dev/loop\-control"); | |
295 | ||
296 | devnr = ioctl(loopctlfd, LOOP_CTL_GET_FREE); | |
297 | if (devnr == \-1) | |
298 | errExit("ioctl\-LOOP_CTL_GET_FREE"); | |
299 | ||
300 | sprintf(loopname, "/dev/loop%ld", devnr); | |
d1a71985 | 301 | printf("loopname = %s\en", loopname); |
1a7f3370 MK |
302 | |
303 | loopfd = open(loopname, O_RDWR); | |
304 | if (loopfd == \-1) | |
305 | errExit("open: loopname"); | |
306 | ||
307 | backingfile = open(argv[1], O_RDWR); | |
308 | if (backingfile == \-1) | |
309 | errExit("open: backing\-file"); | |
310 | ||
311 | if (ioctl(loopfd, LOOP_SET_FD, backingfile) == \-1) | |
312 | errExit("ioctl\-LOOP_SET_FD"); | |
313 | ||
314 | exit(EXIT_SUCCESS); | |
315 | } | |
e7d0bb47 | 316 | .EE |
d8026103 | 317 | .SH SEE ALSO |
8e85a9cc MK |
318 | .BR losetup (8), |
319 | .BR mount (8) |