]>
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 MK |
84 | struct loop_info { |
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 */ | |
89 | int lo_offset; | |
90 | int lo_encrypt_type; | |
91 | int lo_encrypt_key_size; /* ioctl w/o */ | |
92 | int lo_flags; /* ioctl r/o */ | |
93 | char lo_name[LO_NAME_SIZE]; | |
94 | unsigned char lo_encrypt_key[LO_KEY_SIZE]; | |
95 | /* ioctl w/o */ | |
96 | unsigned long lo_init[2]; | |
97 | char reserved[4]; | |
98 | }; | |
b8302363 | 99 | .EE |
e646a1ba | 100 | .in |
5b539973 | 101 | .IP |
5cb4874e MK |
102 | The encryption type |
103 | .RI ( lo_encrypt_type ) | |
104 | should be one of | |
8e85a9cc MK |
105 | .BR LO_CRYPT_NONE , |
106 | .BR LO_CRYPT_XOR , | |
107 | .BR LO_CRYPT_DES , | |
108 | .BR LO_CRYPT_FISH2 , | |
109 | .BR LO_CRYPT_BLOW , | |
110 | .BR LO_CRYPT_CAST128 , | |
111 | .BR LO_CRYPT_IDEA , | |
112 | .BR LO_CRYPT_DUMMY , | |
113 | .BR LO_CRYPT_SKIPJACK , | |
114 | or (since Linux 2.6.0) | |
115 | .BR LO_CRYPT_CRYPTOAPI . | |
5b539973 | 116 | .IP |
56b4a66a MK |
117 | The |
118 | .I lo_flags | |
119 | field is a bit mask that can include zero or more of the following: | |
120 | .RS | |
121 | .TP | |
122 | .BR LO_FLAGS_READ_ONLY | |
123 | The loopback device is read-only. | |
124 | .TP | |
125 | .BR LO_FLAGS_AUTOCLEAR " (since Linux 2.6.25)" | |
126 | .\" commit 96c5865559cee0f9cbc5173f3c949f6ce3525581 | |
127 | The loopback device will autodestruct on last close. | |
128 | .TP | |
129 | .BR LO_FLAGS_PARTSCAN " (since Linux 3.2)" | |
130 | .\" commit e03c8dd14915fabc101aa495828d58598dc5af98 | |
131 | Allow automatic partition scanning. | |
132 | .RE | |
8e85a9cc MK |
133 | .TP |
134 | .B LOOP_GET_STATUS | |
135 | Get the status of the loop device. | |
136 | The (third) | |
137 | .BR ioctl (2) | |
138 | argument must be a pointer to a | |
139 | .IR "struct loop_info" . | |
5210b796 | 140 | .TP |
14ae756a MK |
141 | .BR LOOP_CHANGE_FD " (since Linux 2.6.5)" |
142 | Switch the backing store of the loop device to the new file identified | |
143 | file descriptor specified in the (third) | |
144 | .BR ioctl (2) | |
145 | argument, which is an integer. | |
146 | This operation is possible only if the loop device is read-only and | |
147 | the new backing store is the same size and type as the old backing store. | |
148 | .TP | |
5210b796 MK |
149 | .BR LOOP_SET_CAPACITY " (since Linux 2.6.30)" |
150 | .\" commit 53d6660836f233df66490707365ab177e5fb2bb4 | |
151 | Resize a live loop device. | |
152 | One can change the size of the underlying backing store and then use this | |
153 | operation so that the loop driver learns about the new size. | |
154 | This operation takes no argument. | |
9d40af2a YX |
155 | .TP |
156 | .BR LOOP_SET_DIRECT_IO " (since Linux 4.10)" | |
157 | .\" commit ab1cb278bc7027663adbfb0b81404f8398437e11 | |
f7eff3e7 MK |
158 | Set DIRECT I/O mode on the loop device, so that |
159 | it can be used to open backing file. | |
38ad8652 | 160 | The (third) |
eb39881d | 161 | .BR ioctl (2) |
38ad8652 | 162 | argument is an unsigned long value. |
f7eff3e7 | 163 | A non-zero represents direct I/O mode. |
89593f2d YX |
164 | .TP |
165 | .BR LOOP_SET_BLOCK_SIZE " (since Linux 4.14)" | |
166 | .\" commit 89e4fdecb51cf5535867026274bc97de9480ade5 | |
38ad8652 MK |
167 | Set the block size of the loop device. |
168 | The (third) | |
eb39881d | 169 | .BR ioctl (2) |
38ad8652 | 170 | argument is an unsigned long value. |
f7eff3e7 MK |
171 | This value must be a power of two in the range |
172 | [512,pagesize]; | |
173 | otherwise, an | |
174 | .B EINVAL | |
175 | error results. | |
8e85a9cc MK |
176 | .PP |
177 | Since Linux 2.6, there are two new | |
178 | .BR ioctl (2) | |
179 | operations: | |
180 | .TP | |
181 | .BR LOOP_SET_STATUS64 ", " LOOP_GET_STATUS64 | |
182 | These are similar to | |
183 | .BR LOOP_SET_STATUS " and " LOOP_GET_STATUS | |
184 | described above but use the | |
185 | .I loop_info64 | |
186 | structure, | |
187 | which has some additional fields and a larger range for some other fields: | |
5b539973 | 188 | .IP |
8e85a9cc | 189 | .in +4n |
b8302363 | 190 | .EX |
8e85a9cc MK |
191 | struct loop_info64 { |
192 | uint64_t lo_device; /* ioctl r/o */ | |
193 | uint64_t lo_inode; /* ioctl r/o */ | |
194 | uint64_t lo_rdevice; /* ioctl r/o */ | |
195 | uint64_t lo_offset; | |
196 | uint64_t lo_sizelimit;/* bytes, 0 == max available */ | |
197 | uint32_t lo_number; /* ioctl r/o */ | |
198 | uint32_t lo_encrypt_type; | |
199 | uint32_t lo_encrypt_key_size; /* ioctl w/o */ | |
200 | uint32_t lo_flags; /* ioctl r/o */ | |
201 | uint8_t lo_file_name[LO_NAME_SIZE]; | |
202 | uint8_t lo_crypt_name[LO_NAME_SIZE]; | |
203 | uint8_t lo_encrypt_key[LO_KEY_SIZE]; /* ioctl w/o */ | |
204 | uint64_t lo_init[2]; | |
205 | }; | |
b8302363 | 206 | .EE |
e646a1ba | 207 | .in |
482ee361 MK |
208 | .SS /dev/loop-control |
209 | Since Linux 3.1, | |
210 | .\" commit 770fe30a46a12b6fb6b63fbe1737654d28e84844 | |
211 | the kernel provides the | |
212 | .I /dev/loop-control | |
213 | device, which permits an application to dynamically find a free device, | |
214 | and to add and remove loop devices from the system. | |
215 | To perform these operations, one first opens | |
216 | .IR /dev/loop-control | |
217 | and then employs one of the following | |
218 | .BR ioctl (2) | |
219 | operations: | |
220 | .TP | |
221 | .B LOOP_CTL_GET_FREE | |
222 | Allocate or find a free loop device for use. | |
223 | On success, the device number is returned as the result of the call. | |
224 | This operation takes no argument. | |
225 | .TP | |
226 | .B LOOP_CTL_ADD | |
227 | Add the new loop device whose device number is specified | |
228 | as a long integer in the third | |
229 | .BR ioctl (2) | |
230 | argument. | |
231 | On success, the device index is returned as the result of the call. | |
232 | If the device is already allocated, the call fails with the error | |
233 | .BR EEXIST . | |
234 | .TP | |
235 | .B LOOP_CTL_REMOVE | |
236 | Remove the loop device whose device number is specified | |
237 | as a long integer in the third | |
238 | .BR ioctl (2) | |
239 | argument. | |
240 | On success, the device number is returned as the result of the call. | |
241 | If the device is in use, the call fails with the error | |
242 | .BR EBUSY . | |
69f351b0 | 243 | .SH FILES |
991f7440 MK |
244 | .TP |
245 | .IR /dev/loop* | |
246 | The loop block special device files. | |
1a7f3370 MK |
247 | .SH EXAMPLE |
248 | The program below uses the | |
249 | .I /dev/loop-control | |
250 | device to find a free loop device, opens the loop device, | |
251 | opens a file to be used as the underlying storage for the device, | |
252 | and then associates the loop device with the backing store. | |
253 | The following shell session demonstrates the use of the program: | |
5b539973 | 254 | .PP |
1a7f3370 | 255 | .in +4n |
b8302363 | 256 | .EX |
1a7f3370 MK |
257 | $ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP |
258 | 10+0 records in | |
259 | 10+0 records out | |
260 | 10485760 bytes (10 MB) copied, 0.00609385 s, 1.7 GB/s | |
261 | $ \fBsudo ./mnt_loop file.img\fP | |
262 | loopname = /dev/loop5 | |
b8302363 | 263 | .EE |
e646a1ba | 264 | .in |
1a7f3370 MK |
265 | .SS Program source |
266 | \& | |
e7d0bb47 | 267 | .EX |
1a7f3370 MK |
268 | #include <fcntl.h> |
269 | #include <linux/loop.h> | |
270 | #include <sys/ioctl.h> | |
271 | #include <stdio.h> | |
272 | #include <stdlib.h> | |
273 | #include <unistd.h> | |
274 | ||
d1a71985 | 275 | #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e |
1a7f3370 MK |
276 | } while (0) |
277 | ||
278 | int | |
279 | main(int argc, char *argv[]) | |
280 | { | |
281 | int loopctlfd, loopfd, backingfile; | |
282 | long devnr; | |
283 | char loopname[4096]; | |
284 | ||
285 | if (argc != 2) { | |
d1a71985 | 286 | fprintf(stderr, "Usage: %s backing\-file\en", argv[0]); |
1a7f3370 MK |
287 | exit(EXIT_FAILURE); |
288 | } | |
289 | ||
290 | loopctlfd = open("/dev/loop\-control", O_RDWR); | |
291 | if (loopctlfd == \-1) | |
292 | errExit("open: /dev/loop\-control"); | |
293 | ||
294 | devnr = ioctl(loopctlfd, LOOP_CTL_GET_FREE); | |
295 | if (devnr == \-1) | |
296 | errExit("ioctl\-LOOP_CTL_GET_FREE"); | |
297 | ||
298 | sprintf(loopname, "/dev/loop%ld", devnr); | |
d1a71985 | 299 | printf("loopname = %s\en", loopname); |
1a7f3370 MK |
300 | |
301 | loopfd = open(loopname, O_RDWR); | |
302 | if (loopfd == \-1) | |
303 | errExit("open: loopname"); | |
304 | ||
305 | backingfile = open(argv[1], O_RDWR); | |
306 | if (backingfile == \-1) | |
307 | errExit("open: backing\-file"); | |
308 | ||
309 | if (ioctl(loopfd, LOOP_SET_FD, backingfile) == \-1) | |
310 | errExit("ioctl\-LOOP_SET_FD"); | |
311 | ||
312 | exit(EXIT_SUCCESS); | |
313 | } | |
e7d0bb47 | 314 | .EE |
d8026103 | 315 | .SH SEE ALSO |
8e85a9cc MK |
316 | .BR losetup (8), |
317 | .BR mount (8) |